Erste Schritte mit den Number Insight APIs von Nexmo auf Koa.js

Nexmo's Number Insight API liefert in Echtzeit Informationen über die Gültigkeit, die Erreichbarkeit und den Roaming-Status einer Telefonnummer und sagt Ihnen, wie Sie die Nummer in Ihrer Anwendung korrekt formatieren können.

Number Insight API gibt es in drei Stufen: Basic, Standardund Fortgeschritten, die jeweils eine zunehmende Menge an Informationen über die abgefragte Telefonnummer zurückgeben. Die erweiterte API ist sowohl asynchron als auch synchron verfügbar.

In diesem Blogbeitrag werden wir uns ansehen, wie man die API mit Node.js und der Koa.js Framework.

Voraussetzungen

• Ein grundlegendes Verständnis von Javascript

• Node.js auf Ihrem Rechner installiert

Vonage API-Konto

Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.

Sind Sie bereit, mit dem Bau zu beginnen?

Erleben Sie nahtlose Konnektivität, Echtzeit-Messaging und kristallklare Sprach- und Videoanrufe - alles auf Knopfdruck.

Dieses Tutorial führt Sie von Anfang an durch den Prozess. Wenn Sie den fertigen Code sehen möchten, können Sie das Git-Repository für dieses Projekt oder es auf Glitch neu mischen. Beachten Sie, dass es leichte Unterschiede bei der Glitch-Implementierung gibt, um der Art und Weise, wie Projekte auf der Plattform gehostet werden, Rechnung zu tragen.

Ein Koa.js-Projekt von Grund auf neu beginnen

Erstellen Sie einen Projektordner auf Ihrem lokalen Rechner und führen Sie dann den folgenden Befehl aus, um ein neues Node.js-Projekt einzurichten.

Dies löst eine Reihe von Eingabeaufforderungen aus, die Ihre package.json Datei erstellt. Wenn Sie möchten, können Sie die Antworten leer lassen und die Standardwerte verwenden.

Configuring package.json

Als nächstes installieren Sie Koa.js. Beachten Sie, dass Koa für ES2015 und die Unterstützung von asynchronen Funktionen Node 7.6.0 oder höher benötigt.

Erstellen Sie eine server.js Datei in Ihrem Projektordner.

Fügen Sie den folgenden Code in Ihre neu erstellte Datei ein.

const Koa = require('koa')

const port = process.env.PORT || 3000
const app = new Koa()

app.use(async ctx => {
  ctx.body = 'Hello Dinosaur ?'
})

const listener = app.listen(port, function() {
  console.log('Your app is listening on port ' + listener.address().port)
})

Führen Sie die server.js Datei aus.

Wenn Sie zu http://localhost:3000 in Ihrem Browser aufrufen, sollten Sie eine leere Seite mit dem Text "Hallo Dinosaurier ?" sehen.

Check that server is running

Sie sollten auch Folgendes installieren dotenvinstallieren, das Ihnen erlaubt, Umgebungsvariablen, die in einer .env Datei gespeicherten Umgebungsvariablen in process.env.

Und nun können Sie die Datei .env Datei erstellen, die mindestens die folgenden Variablen enthalten sollte:

NEXMO_API_KEY=''
NEXMO_API_SECRET=''

Um auf Umgebungsvariablen zugreifen zu können, müssen Sie sie anfordern, idealerweise am Anfang Ihrer server.js Datei.

require('dotenv').config()

Wenn Sie sich noch nicht für einen Nexmo Account angemeldet haben haben, ist jetzt ein guter Zeitpunkt, dies zu tun. Sobald Sie sich im Dashboard angemeldet haben, sollten Ihre API-Anmeldedaten das erste sein, was Sie sehen. Achten Sie darauf, sowohl Ihren Schlüssel als auch Ihr Geheimnis in Anführungszeichen zu setzen.

Kennenlernen der Number Insights API

Installieren Sie zunächst den Nexmo REST API-Client für Node.js:

Als nächstes initialisieren Sie eine neue Nexmo-Instanz.

const Nexmo = require('nexmo')

const nexmo = new Nexmo({
  apiKey: process.env.NEXMO_API_KEY,
  apiSecret: process.env.NEXMO_API_SECRET
})

Wie bereits erwähnt, gibt es drei Ebenen für die Number Insight API, und Sie können je nach Art der benötigten Informationen eine auswählen. So ist die API aufgebaut.

nexmo.numberInsight.get({
  level: 'basic | standard | advancedSync', // set Number Insight level here
  number: INSIGHT_NUMBER // phone number to be queried
}, (error, result) => {
  if (error) {
    console.error(error)
  }
  else {
    console.log(result)
  }
})

Sie können sich auf unsere API-Referenz um zu sehen, wie die JSON-Antwort strukturiert ist.

Einsicht in die Zahlen erhalten

Sie benötigen eine Möglichkeit, die abzufragende Telefonnummer einzugeben, also erstellen wir eine einfache Webseite, um dies zu tun.

Erstellen Sie einen public Ordner in Ihrem Projekt und fügen Sie ein index.html, styles.css und scripts.js zu dem Ordner hinzu. Ihre Projektstruktur sollte nun etwa so aussehen:

Fügen Sie die folgende index.html Seite:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Number Insight API</title>
    <meta name="description" content="Exploring Nexmo's Number Insight API">
    <link id="favicon" rel="icon" href="https://www.nexmo.com/favicon.ico" type="image/x-icon">
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <link rel="stylesheet" href="styles.css">
    <script src="scripts.js" defer></script>
  </head>

  <body>
    <main>
      <h1>Retrieve Number Insights</h1>
      <form>
        <input type="tel" placeholder="Enter phone number">
        <button type="button">Submit</button>
      </form>
      <hr>
      <pre><code>Awaiting results…</code></pre>
    </main>
  </body>
</html>

Sie können der Seite auch einige grundlegende Stile hinzufügen, indem Sie Folgendes in die styles.css Datei hinzufügen:

@import url('https://fonts.googleapis.com/css?family=Gudea:400,700');

html {
  box-sizing: border-box;
  height: 100%;
  font-size: calc(1vmin + 1em);
}

*,
*::before,
*::after {
  box-sizing: inherit;
  margin: 0;
  padding: 0;
}

body {
  font-family: 'Gudea', sans-serif;
  height: 100%;
  display: flex;
  flex-direction: column;
  min-width: 15em;
  background-color: gainsboro;
}

main {
  flex: 1;
  margin: auto;
  padding: 1em;
}

h1 {
  margin-bottom: 0.5em;
}

form {
  display: flex;
  align-items: center;
  width: 100%;
  min-width: 10em;
}

input {
  font-size: inherit;
  padding: 0.5em;
  border: 0;
  flex: 1;
}

button {
  font-size: inherit;
  height: 100%;
  background-color: #2e689b;
  color: #fff;
  padding: 0.5em 0.75em;
  border: 0;
}

hr {
  margin: 1em 0;
}

pre {
  background-color: #333;
  padding: 0.5em;
  border-radius: 0.5em;
  color: lightblue;
  white-space: pre-wrap;
}

Der nächste Schritt besteht darin, die Eingabe an den Server zu senden, damit Sie sie mit der Number Insight API verbinden und überprüfen können. Dazu lösen Sie eine POST Anfrage an eine Route, die den Formularinhalt verarbeitet. Der Beispielcode unten verwendet die Fetch-API für diesen Zweck.

const phone = document.querySelector('input')
const submit = document.querySelector('button')
const insights = document.querySelector('code')

submit.addEventListener('click', send, false)

function send(event) {
  fetch('/submit', {
    method: 'post',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone: phone.value
    })
  })
  .then(function(res){ return res.json() })
  .then(function(insight){ parseInsight(insight) })
  .catch(function(error){ console.log(error) })
}

function parseInsight(data) {
  insights.innerHTML = JSON.stringify(data, null, 2)
}

Sie müssen diese Anfrage POST Anfrage auf der Serverseite bearbeiten. Im Gegensatz zu anderen beliebten Node.js-Frameworks wie Express oder Hapi.js ist Koa.js viel modularer. Funktionen wie Routing oder das Ausliefern statischer Dateien werden unterstützt, allerdings in separaten Modulen, die installiert werden müssen:

npm install koa-router koa-bodyparser koa-static --save

Aktualisieren Sie Ihre server.js Datei, um diese neuen Abhängigkeiten zu verwenden. Zuerst, anstatt eine "Hallo Dinosaurier! ?" anzuzeigen, ändern Sie Ihre server.js Datei so, dass sie stattdessen die index.html Datei zu verwenden. Ersetzen Sie

app.use(async ctx => {
  ctx.body = 'Hello Dinosaur ?'
})

mit

const serve = require('koa-static')
app.use(serve('./public'))

Als nächstes richten Sie die Route für eingehende POST-Anfragen an /submit.

const bodyParser = require('koa-bodyparser')
const Router = require('koa-router')

const router = new Router()

app.use(bodyParser())

router.post('/submit', async (ctx, next) => {
  const payload = await ctx.request.body
  const number = await payload.phone
  const insight = await getInsight(number)
  ctx.status = 200
  ctx.body = insight
})

async function getInsight(number) {
  return new Promise(function(resolve, reject){
    nexmo.numberInsight.get({
      level: 'basic', 
      number: number
    }, (error, result) => {
      if (error) {
        console.error(error)
        reject(error)
      }  
      else {
        resolve(result)
      }
    })
  })
}

app.use(router.routes()).use(router.allowedMethods())

Basis-API

Wenn alles richtig eingerichtet ist, sollten Sie in der Lage sein, eine Telefonnummer einzugeben und die entsprechenden Informationen über diese Nummer auf Ihrer Webseite abzurufen. Mit der Basis-API können Sie ermitteln:

• Das Land, in dem eine Nummer registriert ist

• Die lokale und internationale Vertretung dieser Zahl

Mit diesen Informationen können Sie herausfinden, zu welchem Land eine Nummer gehört, und diese Informationen nutzen, um die Nummer richtig zu formatieren.

Basic Number API

Standard-API

Die Number Insight Standard API bietet alle Informationen der Number Insight Basic API zusammen mit den folgenden zusätzlichen Daten:

• Art des Anschlusses (Mobil-/Festnetzanschluss/virtuelle Nummer/Premium/gebührenfrei)

• Der Mobile Country Code (MCC) und der Mobile Network Code (MNC)

• Der Name des Anrufers (nur USA)

Ein üblicher Anwendungsfall wäre die Bestimmung der besten Kommunikationsart für eine Nummer (SMS oder Voice) und die Sperrung virtueller Nummern.

Standard Number API

Erweiterte API

Schließlich bietet die Number Insight Advanced API alle Daten der Number Insight Standard API zusammen mit den folgenden zusätzlichen Informationen:

• Wenn die Nummer wahrscheinlich gültig ist

• Wenn die Nummer portiert wird

• Wenn die Nummer erreichbar ist

• ob es sich um eine Roamingnummer handelt und, falls ja, den Anbieter und das Land

Häufig werden solche Informationen verwendet, um das mit einer Zahl verbundene Risiko zu bestimmen.

Advanced Number API

Die Advanced Number API kann auch asynchron verwendet werden verwendet werden, um die Einsichtsdaten über einen Webhook zurückzugeben, sobald sie verfügbar sind. Beachten Sie, dass diese Funktion für die Basis- und Standard-APIs nicht verfügbar ist.

Wie geht es weiter?

Wenn Sie mehr mit diesen APIs machen wollen, finden Sie hier einige Links, die Ihnen helfen könnten:

• Dokumentation für die Number Insight API auf dem Entwicklerportal

• Reihe von Anleitungen für verschiedene Nexmo APIs

• Wenn Sie uns brauchen, versuchen Sie den Nexmo Community Slack-Kanal

• Lassen Sie uns wissen, was Sie denken, indem Sie tweeten unter @NexmoDev