Postmanでの変数の使用とリクエストの連結

Vonageでは、すべてのAPIを記述するためにOpenAPIを使用しています。 を公開しています。.私たちが見たことのないOpenAPIファイルを使って行うお気に入りのことのひとつは、それを Postman.というわけで、私たちはこのプロジェクトに貢献するために Postmanコレクションを作成することにしました。

この記事では、PostmanでAPIを探索する方法を紹介します。使用するのは Vonage API Postmanコレクションを例として使うので、それに従いたい場合は前提条件のリストを必ず読んでください。

前提条件

• ポストマン・アカウント

変数はあなたの友達

最初に Vonage APIコレクションをインポートすると Vonage APIフォルダが コレクションフォルダが表示されます。

また "36のリクエスト"と表示されていることに気づくかもしれない。認証タイプにもよりますが、これは多かれ少なかれ、36回誰かが api_keyと api_secretをリクエストパラメータとして追加しなければならない。

幸いなことに、Postmanは環境変数、グローバル変数、コレクションレベル変数をサポートしています。リクエストごとに同じパラメータ値を入力するような作業を繰り返す代わりに、これらの変数によって動的に値を取り込むことができます。

私たちのコレクションには Vonage環境でキーとシークレットを提供することができます。

こうすることで、口座残高を確認するような単純なリクエストを Account APIで口座残高を確認するような簡単なリクエストは、ワンクリックでできるようになる。

その他のリクエストの中には、追加のパラメータが必要なものもある。例えば SMSを送信するには to, fromと textを記入する必要があるが api_keyと api_secretは自動入力されます。のように、これらのパラメータを変数として追加することもできます。 toのように、これらのパラメータを変数として追加することもできます。コレクションや環境を直接編集するか、変数に置き換えたいハードコードされた値を選択して 変数として設定> 新しい変数として設定.

リクエストの連鎖

Postmanの変数は素晴らしいが、あらゆる面倒なことを解決する万能ツールではない。
例えば、JWTを使って認証するVonage APIを使う場合、リクエストをする前にJWTを生成する必要がある。JWTを生成するには、アプリケーションIDと秘密鍵が必要で、どちらもVonageアプリケーションを作成すると入手できます。これは3つの別々のリクエストになり、初めてAPIを使う人を混乱させる可能性があります。

幸運なことに、複数ステップの前提条件にも回避策がある。
Postmanには2つのスクリプトエリアがあります、 リクエスト前スクリプトと テストという2つのスクリプトエリアがあり、好きなJavaScriptコードを書くことができます。

プレリクエスト・スクリプト

Vonage Voice APIはJSON Web Tokens (JWT)を使って認証を行うため、次のような送信を行うことができます。 発信コールの作成リクエストを送信するには、まず

1. Applications APIを使用したVonageアプリケーションの作成

2. をつかむ。 application_idと private_key値を取得し、それを使ってJWTを生成する。

// Check if we already have a JSON Web Token, continue if not
if (!pm.environment.has("JWT")) {
    var btoa = require('btoa')
    let base64keyandsecret = btoa(`${pm.environment.get("api_key")}:${pm.environment.get("api_secret")}`)

// (1) Create a Voice Application by making a request to the Vonage Applications API
    pm.sendRequest({
        url: 'https://api.nexmo.com/v2/applications',
        method: 'POST',
        header: [`Authorization:Basic ${base64keyandsecret}`, "Content-Type: application/json"],
        body: JSON.stringify({
            "name": "Demo Postman Application",
            "capabilities": {
                "voice": {
                    "webhooks": {
                        "answer_url": {
                            "address": "https://example.com/webhooks/answer",
                            "http_method": "POST"
                        },
                        "event_url": {
                            "address": "https://example.com/webhooks/event",
                            "http_method": "POST"
                        }
                    }
                }
            }
        })
    }, (err, res) => {
// (2) Generate JWT using the application ID as a claim and sign it with the private key
        pm.sendRequest({
            url: 'https://jwtapi-dev.netlify.app/.netlify/functions/generate',
            method: 'POST',
            header: ["Content-Type: application/json"],
            body: JSON.stringify({
                algorithm: "RS256",
                private_key: res.json().keys.private_key,
                claims: {
                    application_id: res.json().id,
                    exp: parseInt((Date.now() / 1000) + 3600, 10)
                }
            })
        }, (err, res) => {
            pm.environment.set("JWT", res.json().signed_jwt)
        })
    })
}

テストなぜポスト・リクエスト・スクリプトではないのか？

Postmanでは、個々のリクエスト、フォルダ、コレクションにテストを追加することができます。これらのテストは、APIが期待通りに動作していることを確認したり、デバッグを行ったりするのに非常に役立ちます。 リクエストの後に実行されるリクエストの後に実行されるJavaScriptスクリプトです。つまり リクエスト前スクリプトを最大限に活用できるということです。 テストエリアも最大限に活用できるということだ。

Voiceコールの例では、正常終了時に、コレクション変数として voice_call_uuidコレクション変数として pm.collectionVariables.set()関数を使ってコレクション変数として保存している。この変数は、Voice APIを含む他のリクエストを行う際に便利です。また、失敗した場合は JWT値をクリアします。 pm.environment.unset("JWT")式を使って値をクリアし、リクエストを再度送信して新しいJWTを生成できるようにしています。

if (pm.response.code == "201") {
    pm.collectionVariables.set("voice_call_uuid", pm.response.json().uuid);
} else {
    pm.environment.unset("JWT")
}

スクリプトでの変数の定義については のドキュメント.

リクエスト・ボディ

最後に、これをまとめて音声合成音声通話をしてみましょう。以下のスニペットを使って toと fromを変数またはハードコードされた値として指定します。を変数またはハードコードした値で指定します。 toはこれからかける相手先の番号で fromはあなたのVonage Numbersの一つです。ダッシュボードで ダッシュボードをダッシュボードで取得してください。

NCCO NCCOはコール・コントロール・オブジェクトで、コールに応答した後に実行されるすべてのアクションをリストアップします。以下の NCCOリファレンスを参照し、コールフローに含めることができる他のアクションを確認してください。

{
    "to": [
        {
            "number": {{to}},
            "type": "phone"
        }
    ],
    "from": {
        "number": {{from}},
        "type": "phone"
    },
    "ncco": [
        {
          "action": "talk",
          "text": "This is a text to speech call from Vonage"
        }
      ]
}

このリクエストは実行可能です。 送信ボタンを押してください。おめでとう！そして、これの一番いいところは何かわかりますか？変更を保存して コレクションを共有を保存すれば、次の人は足りない変数値を埋めて 送信ボタンを押すだけです。

Postmanの便利な機能をどのように使いますか？何かヒントやコツはありますか？あなたのアイデアを楽しみにしています！

次はどこだ？

• Vonage APIs Postmanコレクションの発表

• Vonage API ポストマンコレクション

• 変数の使用ガイド

• Account API リファレンス

• SMS API リファレンス

• Voice API NCCO リファレンス