Wie man von Pricing API v1 zu Pricing API v2 migriert

Übersicht

In diesem Leitfaden wird erklärt, wie Sie von der Pricing API v1 auf die Pricing API v2 migrieren. Die neue Version der Pricing API enthält Änderungen an der Authentifizierung, den Routen und den Antwortstrukturen. Dieser Leitfaden dokumentiert die Änderungen, die Sie an Ihrer Anwendung vornehmen müssen, damit Sie Ihre Integration aktualisieren können.

Die Umstellung auf die Pricing API v2 ist wichtig, um die Vorteile der verbesserten Konsistenz, Sicherheit und Flexibilität der neuen API zu nutzen.

Bevor Sie beginnen

Bevor Sie mit der Migration beginnen, sollten Sie sicherstellen, dass:

Sie haben Ihren bestehenden Vonage API-Schlüssel und Ihr API-Geheimnis.
Sie haben diese Dokumentation gelesen, um die neuen Funktionen und Möglichkeiten zu verstehen.
Sie verfügen über eine Test- oder Entwicklungsumgebung, in der Sie Änderungen testen können, bevor Sie sie in der Produktion einsetzen.

Beachten Sie die URL Änderung

Die Pricing API v2 verwendet eine neue Basis-URL für die API im Vergleich zu v1.

Ändern Sie in Ihrer Anwendung die Basis-URL und die Route von https://rest.nexmo.com/account/get-pricing/outbound/ zu https://api.nexmo.com/v2/account/pricing/

// Example using the old route
const apiKey = 'vonage_api_key'; // Replace with your API Key
const apiSecret = 'vonage_api_secret'; // Replace with your API Secret
const product = 'sms'; // Example product
const country = 'CA'; // Example country code

const url = `https://rest.nexmo.com/account/get-pricing/outbound/${product}?api_key=${apiKey}&api_secret=${apiSecret}&country=${country}`;

// Example using the new route
const apiKey = 'vonage_api_key'; // Replace with your API Key
const apiSecret = 'vonage_api_secret'; // Replace with your API Secret
const product = 'sms-outbound'; // Example product
const country = 'CA'; // Example country code

const url = `https://api.nexmo.com/v2/account/pricing/${product}`

Wählen Sie das geeignete Produkt

Die Pricing API v2 unterstützt nur sms-outbound und voice-outboundim Vergleich zur Pricing API v1, die Folgendes unterstützte sms, sms-transitund voice. Sie müssen sich vergewissern, dass Sie den entsprechenden Produktnamen anrufen, da sich dieser ändern wird. In den meisten Fällen sms-transit und sms kann geändert werden in sms-outboundund voice kann geändert werden in voice-outbound.

Umstellung auf Basic Header Authentication

Die Pricing API v1 nutzte die Abfrageparameter-Authentifizierung, um Ihre Anfrage zu validieren, und die Pricing API v2 nutzt nun die Basis-Authentifizierung unter Verwendung der Authorization Kopfzeile.

Suchen Sie die API-Anforderung in Ihrer aktuellen Anwendung. Wenn Sie Node.js verwenden, können Ihre Anfragen wie die folgenden aussehen:

const fetch = require('node-fetch');

const apiKey = 'vonage_api_key'; // Replace with your API Key
const apiSecret = 'vonage_api_secret'; // Replace with your API Secret
const product = 'sms'; // Example product
const country = 'CA'; // Example country code

const url = `https://rest.nexmo.com/account/get-pricing/outbound/${product}?api_key=${apiKey}&api_secret=${apiSecret}&country=${country}`;

fetch(url)
    .then(response => {
        if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
        }
        return response.json();
    })
    .then(data => {
        console.log('Pricing Data:', data);
    })
    .catch(error => {
        console.error('Error fetching pricing data:', error);
    });

const axios = require('axios');

const apiKey = 'vonage_api_key'; // Replace with your API Key
const apiSecret = 'vonage_api_secret'; // Replace with your API Secret
const product = 'sms-outbound'; // Example product
const country = 'CA'; // Example country code

const url = `https://rest.nexmo.com/account/get-pricing/outbound/sms`;

axios
    .get(url, {
        params: {
        api_key: apiKey,
        api_secret: apiSecret,
        country: country,
        },
    })
    .then(response => {
        console.log('Pricing Data:', response.data);
    })
    .catch(error => {
        console.error('Error fetching pricing data:', error.response ? error.response.data : error.message);
    });

Entfernen Sie die api_key und api_secret Parameter, und ersetzen Sie sie durch eine Authentication Kopfzeile, die Basic-Authentifizierung verwendet.

// Example using Node Fetch
const fetch = require('node-fetch');

const apiKey = 'vonage_api_key'; // Replace with your API Key
const apiSecret = 'vonage_api_secret'; // Replace with your API Secret
const product = 'sms-outbound'; // Example product
const country = 'CA'; // Example country code

const url = `https://api.nexmo.com/v2/account/pricing/${product}?country=${country}`;

fetch(url, {
    method: 'GET',
    headers: {
        Authorization: `Basic ${Buffer.from(`${apiKey}:${apiSecret}`).toString('base64')}`,
    },
})
    .then(response => {
        if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
        }
        return response.json();
    })
    .then(data => {
        console.log('Pricing Data:', data);
    })
    .catch(error => {
        console.error('Error fetching pricing data:', error);
    });

// Example using Axios
const axios = require('axios');

const apiKey = 'vonage_api_key'; // Replace with your API Key
const apiSecret = 'vonage_api_secret'; // Replace with your API Secret
const product = 'sms-outbound'; // Example product
const country = 'CA'; // Example country code

const url = `https://api.nexmo.com/v2/account/pricing/${product}`;

axios
    .get(url, {
        auth: {
            username: username,
            password: password,
        },
        params: {
            country: country,
        },
    })
    .then(response => {
        console.log('Pricing Data:', response.data);
    })
    .catch(error => {
        console.error('Error fetching pricing data:', error.response ? error.response.data : error.message);
    });

Änderung zur Verarbeitung der neuen Antwortstruktur

Die Pricing API v2 verwendet jetzt eine JSON-HAL Antwortstruktur, um die Konsistenz mit anderen Vonage-APIs zu erhöhen. Dies ist eine andere API-Antwortstruktur als die flachere Antwortstruktur der Pricing-API v1, bietet aber einige zusätzliche Vorteile wie z. B. eine bessere Paginierung der Ergebnisse.

Beachten Sie die Änderung des Speicherorts der Daten in der Antwort. Die Preis- und Netzinformationen befinden sich jetzt in der Datei _embedded.countries Array anstelle des networks Array.

// Pricing API v1 Response
{
    "countryCode": "CA",
    "countryName": "Canada",
    "countryDisplayName": "Canada",
    "currency": "EUR",
    "defaultPrice": "0.00620000",
    "dialingPrefix": "1",
    "networks": [
        {
            "type": "mobile",
            "price": "0.00590000",
            "currency": "EUR",
            "mcc": "302",
            "mnc": "530",
            "networkCode": "302530",
            "networkName": "Keewaytinook Okimakanak"
        }
    ]
}

// Pricing API v2 Response
{
    "page_size": "100",
    "page": "1",
    "total_items": "243",
    "total_pages": "3",
    "_embedded": {
        "countries": [
            {
                "country_name": "Canada",
                "dialing_prefix": "1",
                "dest_network_type": "ALL",
                "group_internal_start": "1s",
                "rate_increment": "60",
                "currency": "USD",
                "price": "0.1"
            }
        ]
    },
    "_links": {
        "self": {
            "href": "https://api.nexmo.com/account/pricing/sms-outbound?page=1&page_size=100"
        },
        "first": {
            "href": "https://api.nexmo.com/account/pricing/sms-outbound?page=1&page_size=100"
        },
        "last": {
            "href": "https://api.nexmo.com/account/pricing/sms-outbound?page=3&page_size=100"
        },
        "next": {
            "href": "https://api.nexmo.com/account/pricing/sms-outbound?page=2&page_size=100"
        },
        "prev": {
            "href": "https://api.nexmo.com/account/pricing/sms-outbound?page=1&page_size=100"
        }
    }
}

Beachten Sie die Änderungen an den Schlüsselnamen. Die Schlüsselnamen verwenden jetzt snake_case anstelle von camelCase. Dies entspricht den API-Standards von Vonage und ist mit unseren anderen API-Antworten konsistent. Einige Standorte der Schlüssel haben sich ebenfalls geändert.

countryCode befindet sich jetzt in der URL als country Abfrageparameter.
countryName befindet sich jetzt unter _embedded.countries[X].country_name.
countryDisplayName befindet sich jetzt unter _embedded.countries[X].country_name.
currency befindet sich jetzt unter _embedded.countries[X].currency.
defaultPrice befindet sich jetzt unter _embedded.countries[X].price.
dialingPrefix befindet sich jetzt unter _embedded.countries[X].dialing_prefix.
network[X].type wird nicht mehr zurückgegeben.
network[X].price befindet sich jetzt unter _embedded.countries[X].price.
network[X].currency befindet sich jetzt unter _embedded.countries[X].currency.
network[X].mcc wird nicht mehr zurückgegeben.
network[X].mnc wird nicht mehr zurückgegeben.
network[X].networkCode wird nicht mehr zurückgegeben.
network[X].networkName wird nicht mehr zurückgegeben.

Die Antwort spiegelt nun das Paging genauer wider. Sie können die page Taste mit der total_pages Taste, um festzustellen, ob Sie sich am Ende der Ergebnisse befinden, oder prüfen Sie, ob die _links.next Taste. Wenn Sie auf die nächste Seite wechseln möchten, können Sie die Taste _links.next.href Wert, um automatisch die nächste Seite zu ermitteln und dorthin zu navigieren.

Siehe auch

Preisgestaltung API v2 OpenAPI-Spezifikation