Pricing API v1からPricing API v2への移行方法

概要

このガイドでは、Pricing API v1 から Pricing API v2 への移行方法を説明します。Pricing API の新バージョンでは、認証、ルート、レスポンス構造が変更されました。このガイドでは、統合を更新するためにアプリケーションに必要な変更を説明します。

新しいAPIによって改善された一貫性、セキュリティ、柔軟性を活用するためには、Pricing API v2への移行が重要です。

始める前に

移行を開始する前に、以下を確認してください：

  • 既存のVonage API KeyとAPI Secretをお持ちです。
  • 新機能を理解するために、このドキュメントをお読みになったことでしょう。
  • 本番環境にデプロイする前に、変更をテストするためのテスト環境や開発環境がある。

URLの変更に注意

Pricing API v2では、v1と比較してAPIのベースURLが新しくなっています。

  1. アプリケーションで、ベースURLとルートを次のように変更してください。 https://rest.nexmo.com/account/get-pricing/outbound/ への 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}`

適切な製品を選ぶ

Pricing API v2 がサポートしているのは、次のものだけです。 sms-outbound そして voice-outboundプライシングAPI v1では、次のような機能がサポートされていた。 sms, sms-transitそして voice.製品名は変更されるため、適切な製品名を呼ぶ必要があります。ほとんどの場合 sms-transit そして sms に変更できる。 sms-outboundそして voice に変更できる。 voice-outbound.

ベーシック・ヘッダ認証への移行

Pricing API v1ではクエリパラメータ認証を使用してリクエストの検証を行っていましたが、Pricing API v2では以下のようなBasic認証を使用するようになりました。 Authorization ヘッダーを使用する。

  1. 現在のアプリケーションでAPIリクエストを見つけてください。Node.jsを使用している場合、リクエストは以下のようになります：

    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);
    });

  2. を取り外す。 api_key そして api_secret パラメータに置き換えてください。 Authentication ヘッダはBasic認証を使用する。

    // 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);
    });

新対応体制への変更

Pricing API v2 では、次のようになりました。 JSON-HAL レスポンス構造を他の Vonage API とより整合性のあるものにしました。これは、Pricing API v1のフラットなレスポンス構造とは異なるAPIレスポンス構造ですが、結果のページングが改善されるなどの利点があります。

  1. レスポンスのデータロケーションの変更に注意してください。価格とネットワーク情報は、現在 _embedded.countries 配列の代わりに networks 配列である。

    // 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"
        }
    }
}

  2. キー名の変更に注意してください。キー名には snake_case の代わりに camelCase.これにより、VonageのAPI標準に準拠し、他のAPIレスポンスとの一貫性が保たれます。キーの位置も一部変更されています。

  • countryCode がURLの country クエリ・パラメータ。
  • countryName は現在 _embedded.countries[X].country_name.
  • countryDisplayName は現在 _embedded.countries[X].country_name.
  • currency は現在 _embedded.countries[X].currency.
  • defaultPrice は現在 _embedded.countries[X].price.
  • dialingPrefix は現在 _embedded.countries[X].dialing_prefix.
  • network[X].type は返されなくなった。
  • network[X].price は現在 _embedded.countries[X].price.
  • network[X].currency は現在 _embedded.countries[X].currency.
  • network[X].mcc は返されなくなった。
  • network[X].mnc は返されなくなった。
  • network[X].networkCode は返されなくなった。
  • network[X].networkName は返されなくなった。
  1. レスポンスはより正確にページングを反映するようになった。このため page キーを total_pages キーで結果の末尾にいるかどうかを確認する。 _links.next キーを使用してください。次のページに移動したい場合は _links.next.href の値を自動的に決定し、次のページにナビゲートする。

参照