チュートリアル: Postman で署名して要求を行う

このチュートリアルでは、Postman を設定して使用することで、HTTP を使って Azure Communication Services に対して要求を行います。 このチュートリアルを終了すると、Communication Services と Postman を使用して、SMS メッセージを正常に送信できるようになります。 さらに、Postman を使用して、Azure Communication Services 内の他の API を探索できるようになります。

このチュートリアルでは、次のことを行います。

• Postman をダウンロードする
• HTTP 要求に署名するように Postman を設定する
• Communication Services SMS API に対し、メッセージを送信するように要求する。

前提条件

• アクティブなサブスクリプションが含まれる Azure アカウント。 詳細については、アカウントの無料作成に関するページを参照してください。 無料アカウントでは 200 ドル分の Azure クレジットが提供され、さまざまな組み合わせのサービスをお試しいただけます。
• アクティブな Communication Services リソースと接続文字列。 Communication Services リソースを作成する方法に関する記事を参照してください。
• SMS メッセージを送信できる Azure Communication Services 電話番号。これを取得するには、電話番号の取得に関する記事を参照してください。

Postman をダウンロードしてインストールする

Postman は、任意の HTTP API に対して API 要求を行うことができるデスクトップ アプリケーションです。 これは、API のテストと探索用に一般に使用されています。 最新のデスクトップ バージョンを Postman の Web サイトからをダウンロードします。 Postman には、Windows、Mac、Linux 用のバージョンがあるため、お使いのオペレーティング システムに適したバージョンをダウンロードしてください。 ダウンロードしたら、アプリケーションを開きます。 スタート画面が表示されます。ここで、サインインするか Postman アカウントを作成するかを尋ねられます。 アカウントの作成はオプションであり、[Skip and go to app](スキップしてアプリに移動) リンクをクリックするとスキップできます。 アカウントを作成すると API 要求の設定が Postman に保存され、他のコンピューターでご自身の要求を取得できるようになります。

アカウントを作成するか作成をスキップすると、Postman のメイン ウィンドウが表示されます。

Postman コレクションを作成して構成する

Postman では、さまざまな方法で要求を整理できます。 このチュートリアルの目的に沿って、 Postman コレクションを作成します。 これを行うには、アプリケーションの左側にある [Collections](コレクション) ボタンを選択します。

選択したら、[Create new Collection](新しいコレクションの作成) をクリックして、コレクションの作成プロセスを開始します。 Postman の中央の領域に新しいタブが開きます。 コレクションに任意の名前を指定します。 ここでは、コレクションに "Azure Communication Services" という名前が付いています。

コレクションを作成し、名前を指定したら、その構成準備ができました。

コレクション変数を追加する

認証を処理するため、および要求をより簡単に行えるようにするために、新しく作成された Communication Services コレクション内に 2 つのコレクション変数を指定します。 これらの変数は、Communication Services コレクション内のすべての要求で使用できます。 変数の作成を開始するには、コレクションの変数のタブにアクセスします。

コレクションのタブを表示したら、次の 2 つの変数を作成します。

• key - この変数は、Azure portal 内の Azure Communication Services のキー ページにあるキーのいずれかでなければなりません。 たとえば、「 oW...A== 」のように入力します。
• endpoint - この変数は、キー ページの Azure Communication Services のエンドポイントでなければなりません。 末尾のスラッシュは必ず削除してください。 たとえば、「 https://contoso.communication.azure.com 」のように入力します。

これらの値を、変数画面の [Initial Value](初期値) 列に入力します。 入力したら、右側のテーブルのすぐ上にある [Persist All](すべて保持) ボタンを押します。 正しく構成されたら、Postman の画面は次のようになります。

変数の詳細については、それに関する Postman のドキュメントを参照してください。

要求前スクリプトを作成する

次の手順では、Postman 内に要求前スクリプトを作成します。 要求前スクリプトは、Postman の各要求の前に実行され、ユーザーに代わって要求パラメーターを修正または変更できるスクリプトです。 これを使用して HTTP 要求に署名し、Azure Communication Services で承認できるようにします。 署名の要件の詳細については、認証に関するガイドを参照してください。

このスクリプトをコレクション内に作成することで、コレクション内の任意の要求で実行されるようにします。 これを行うには、コレクションのタブで、[Pre-request Script](要求前スクリプト) サブタブをクリックします。

このサブタブでは、要求前スクリプトを下のテキスト領域に入力して作成できます。 これは、Visual Studio Code などの高機能のコード エディター内で記述してから、完成時に貼り付ける方が簡単な場合があります。 このチュートリアルでは、スクリプトの各部分について説明します。 単に Postman にコピーして作業を開始する場合は、最後までスキップしてもかまいません。 それではスクリプトの記述を始めます。

要求前スクリプトを記述する

まず、協定世界時 (UTC) の文字列を作成し、これを "Date" HTTP ヘッダーに追加します。 また、この文字列を変数に格納し、後で署名時に使用します。

// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});

次に、SHA 256 を使用して要求本文をハッシュし、x-ms-content-sha256 ヘッダーに挿入します。 Postman には、グローバルでハッシュと署名を行うための標準ライブラリがいくつか含まれているため、これらをインストールする必要はなく、これらが必要になることもありません。

// Hash the request body using SHA256 and encode it as Base64
const hashedBodyStr = CryptoJS.SHA256(pm.request.body.raw).toString(CryptoJS.enc.Base64)
// And add that to the header x-ms-content-sha256
pm.request.headers.upsert({
    key:'x-ms-content-sha256',
    value: hashedBodyStr
});

ここでは、前に指定したエンドポイント変数を使用して、HTTP ホスト ヘッダーの値を識別します。 ホスト ヘッダーはこのスクリプトが処理されるまで設定されないため、これを行う必要があります。

// Get our previously specified endpoint variable
const endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" value
const hostStr = endpoint.replace('https://','');

この情報を作成したら、HTTP 要求に署名する文字列を作成できます。これは、前に作成されたいくつかの値で構成されます。

// This gets the part of our URL that is after the endpoint, for example in https://contoso.communication.azure.com/sms, it will get '/sms'
const url = pm.request.url.toString().replace('{{endpoint}}','');

// Construct our string which we'll sign, using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;

最後に、Communication Services キーを使用してこの文字列に署名してから、それを Authorization ヘッダー内で要求に追加する必要があります。

// Decode our access key from previously created variables, into bytes from base64.
const key = CryptoJS.enc.Base64.parse(pm.variables.get('key'));
// Sign our previously calculated string with HMAC 256 and our key. Convert it to Base64.
const signature = CryptoJS.HmacSHA256(stringToSign, key).toString(CryptoJS.enc.Base64);

// Add our final signature in Base64 to the authorization header of the request.
pm.request.headers.upsert({
    key:'Authorization',
    value: "HMAC-SHA256 SignedHeaders=date;host;x-ms-content-sha256&Signature=" + signature
});

最終的な要求前スクリプト

最終的な要求前スクリプトはこちらのようになります。

// Set the Date header to our Date as a UTC String.
const dateStr = new Date().toUTCString();
pm.request.headers.upsert({key:'Date', value: dateStr});

// Hash the request body using SHA256 and encode it as Base64
const hashedBodyStr = CryptoJS.SHA256(pm.request.body.raw).toString(CryptoJS.enc.Base64)
// And add that to the header x-ms-content-sha256
pm.request.headers.upsert({
    key:'x-ms-content-sha256',
    value: hashedBodyStr
});

// Get our previously specified endpoint variable
const endpoint = pm.variables.get('endpoint')
// Remove the https, prefix to create a suitable "Host" value
const hostStr = endpoint.replace('https://','');

// This gets the part of our URL that is after the endpoint, for example in https://contoso.communication.azure.com/sms, it will get '/sms'
const url = pm.request.url.toString().replace('{{endpoint}}','');

// Construct our string which we'll sign, using various previously created values.
const stringToSign = pm.request.method + '\n' + url + '\n' + dateStr + ';' + hostStr + ';' + hashedBodyStr;

// Decode our access key from previously created variables, into bytes from base64.
const key = CryptoJS.enc.Base64.parse(pm.variables.get('key'));
// Sign our previously calculated string with HMAC 256 and our key. Convert it to Base64.
const signature = CryptoJS.HmacSHA256(stringToSign, key).toString(CryptoJS.enc.Base64);

// Add our final signature in Base64 to the authorization header of the request.
pm.request.headers.upsert({
    key:'Authorization',
    value: "HMAC-SHA256 SignedHeaders=date;host;x-ms-content-sha256&Signature=" + signature
});

この最終的なスクリプトを、[Pre-request Script](要求前スクリプト) タブ内のテキスト領域に入力するか貼り付けます。

入力したら、CTRL + S キーを押すか、[Save](保存) ボタンを押します。これで、スクリプトがコレクションに保存されます。

Postman で要求を作成する

すべてが設定されたので、Postman 内で Communication Services 要求を作成する準備ができました。 開始するには、Communication Services コレクションの横にある正符号 (+) アイコンをクリックします。

これにより、Postman 内に要求のための新しいタブが作成されます。 作成したら、それを構成する必要があります。 SMS Send API に対して要求を行うので、詳細についてこちらの API のドキュメントを参照してください。 それでは Postman の要求を構成します。

まず、要求の種類を POST に設定し、要求の URL フィールドに「{{endpoint}}/sms?api-version=2021-03-07」と入力します。 この URL では、前に作成した endpoint 変数を使用して、Communication Services リソースに自動的に送信されるようにします。

次に、要求の [Body](本文) タブを選択し、下にあるオプション ボタンを [raw](生) に変更します。 右側には、"Text" ドロップダウンがあり、これを JSON に変更します。

これで、情報が JSON 形式で送受信されるように要求が構成されます。

下のテキスト領域には要求本文を入力する必要があり、次の形式にします。

{
    "from":"<Your Azure Communication Services Telephone Number>",
    "message":"<The message you'd like to send>",
    "smsRecipients": [
        {
            "to":"<The number you'd like to send the message to>"
        }
    ]
}

"from" の値については、前述のように Azure Communication Services ポータルで電話番号を取得する必要があります。 スペースを含めずに、プレフィックスとして国番号を付けて入力します。 たとえば、+15555551234 のように指定します。 "message" は送信したい内容であればどのようなものでもかまいませんが、Hello from Azure Communication Services は適例です。 "to" 値は、SMS メッセージを受信できる、ご自身がアクセスできる電話にしてください。 ご自身のモバイルを使用することをお勧めします。

入力したら、前に作成した Communication Services コレクションにこの要求を保存する必要があります。 これにより、前に作成した変数と要求前スクリプトが確実に取得されます。 これを行うには、要求領域の右上にある [Save](保存) ボタンをクリックします。

これによってダイアログ ウィンドウが表示され、要求の名前とその保存場所を指定するように求められます。 任意の名前を指定できますが、ダイアログ下部で確実にご自身の Communication Services コレクションを選択してください。

要求を送信する

すべてが設定されたので、要求を送信して、ご自身の電話で SMS メッセージを取得できます。 これを行うには、作成した要求が選択されていることを確認し、右側にある [Send](送信) ボタンを押します。

すべて問題なく完了したら、Communication Services からの応答が表示され、202 という状態コードになっているはずです。

"to" 値に指定した番号を持つ携帯電話も SMS メッセージを受信しているはずです。 これで、Azure Communication Services と通信して SMS メッセージを送信するための機能的な Postman 構成を作成できました。

次のステップ

Azure Communication Services API を探索する認証の詳細を参照するPostman の詳細を学習する

次の記事もご覧ください。

• チャットをアプリに追加する
• ユーザー アクセス トークンを作成する
• クライアントとサーバーのアーキテクチャについて学習する
• 認証について学習する