Azure API Managementを利用してHTTPの基本を学ぼう

鈴木源 - Nomura Research Institute, Ltd.

はじめに

こんにちは、NRIの鈴木源です。
主にAzureを活用したプロジェクトにおいて、要件定義・設計・構築・運用と幅広く担当しています。

今回のブログでは、Azureが提供するAPI Management（以下APIM）を利用して、HTTPの基本を習得する為の学習課題を紹介します。
NRIでは、Azureのプロジェクトチームに新規参加する若手メンバーが「Azure＋インフラ技術」の両方を学習する課題として利用しています。

対象読者：

　若手エンジニア（新卒入社～3年目ぐらい）でWEBアプリケーションやサーバを担当している人

　若手エンジニアの育成を担当しており、学習課題の題材に困っている人

準備いただきたいもの：

　Azure アカウント

本課題を通して学習できるHTTPの基本的な要素：

HTTPメソッド(GET/POST)

HTTPステータスコード

HTTPヘッダー/URLクエリパラメータ

注意事項
Azureサービスを利用する場合には利用料金が掛かります。
利用時間に応じての課金のため、課題完了後は速やかにリソースを削除しましょう。今回のリソースは学習目的での簡易的な設定のみ実施しています。商用利用する場合には設計・設定がサービスの要件を満たせるのかを十分に確認し、検証してください。

azure.microsoft.com

はじめに
目次
課題を始める前の基礎知識
課題１．APIMインスタンスを作成しよう
課題２．モック応答のAPI(GET/POST)を作成しよう
課題３．認証キー情報を付与してリクエストしよう
まとめ
お問い合わせ
関連リンク・トピックス
- 採用情報

課題を始める前の基礎知識

HTTP通信におけるクライアントとサーバ
HTTPはクライアントがサーバにリクエストを送信し、サーバがレスポンスを返す形で通信が行われます。今回の課題ではクライアントであるウェブブラウザ（ChromeやEdgeなど）から、サーバと見立てたAPIMにリクエストを送信します。
HTTPメソッド(GET/POST)
クライアントがサーバに対して行いたいアクションを指定するためのものです。ウェブブラウザやAPIクライアントがサーバにリクエストを送る際に、このメソッドを使ってリクエストの種類を示します。

HTTPメソッドにはGET/POST以外にもPUT/DELETEなどの種類がありますが、基本となるGET/POSTを学びます。
- GET: サーバからデータを取得するリクエスト。例えば、ウェブページや画像を表示するためのデータを要求します。リクエストのボディ部分は通常ありません。URLクエリパラメータを使って情報を送ることがあります。
- POST: サーバにデータを送信するリクエスト。フォームの送信やファイルのアップロードなどに使用されます。データをリクエストボディに含めて送信します。
HTTPステータスコード
サーバからのレスポンスに含まれる番号で、リクエストの成功やエラーを示します。
今回の課題で発生する可能性のあるエラーコードは以下の3種類です。
- 200番台：リクエストの成功です。クライアントからのリクエストがサーバに送られ処理された状態です。
- 400番台：クライアント側のエラーです。操作や入力に不備があった際に出てしまうエラーで、今回の課題ではよく目にするエラーのはずです。400番台のエラーが発生した場合には、そのエラーが何を意味するのか調べてみましょう。
  - 401 Unauthorized：クライアントにアクセス権がない、もしくは認証のエラーです。正しい認証情報を入力する必要があります。
  - 404 Not Found：リクエスト先のページが存在しません。URLが正しいか確認しましょう。
- 500番台：サーバ側のエラーです。クライアント側では復旧するまで何も出来ることはありません。今回の課題では500番台のエラーが出ることは想定していません。Azureサービスの一時的な問題な可能性があるため、しばらく時間をおいてから再度課題を実施してください。
HTTPヘッダー
リクエストやレスポンスに付加される情報です。たとえば、ブラウザの種類や言語設定、どの形式のデータを受け取るかなどが含まれます。
「百聞は一見に如かず」ということで、ウェブブラウザを起動してF12開発者モードを実行してネットワークタブを開きながら、何でも良いので検索してみましょう。
表示されたリクエストのいずれかを選択すると「Response Headers」や「Request Headers」を確認することができます。
URLクエリパラメータ
URLクエリパラメータはサーバへ送りたいデータを指定するためにURLの最後に追加する文字列です。主にGETメソッドで利用されます。

課題１．APIMインスタンスを作成しよう

■目的
Azure Portal を使用して新しい APIMインスタンスを作成します。

■実践
下記クイックスタートの内容に沿って実施してください。作成を押してから実際に利用可能になるまで時間がかかります。2時間程度待つこともありましたので、気長に完了を待ってください。

クイックスタート - Azure API Management インスタンスを作成する - ポータル | Microsoft Learn
※クイックスタート内の「リソースをクリーンアップする」の項はまだ実施しないでください。

■APIM作成時の指定パラメータ
今回は課題実施のための作成なので、[基本]タブで設定するリージョンは問いませんが、価格レベルは必ず[Developer]を選択してください。SKUや一部機能制限はありますが、他の価格レベルと比較して安価です。尚、サービス開発で利用する際には、価格レベルごとの機能差異は必ず調査してください。

※2024/9/20現在の東日本リージョンでのAPIMの料金は以下の通り。

・Developer：6,941円/月

・Basic：21,267/月

・Standard：99,240/月

・Premium：403,944/月

API Management の価格 | Microsoft Azure

■ゴール

[API Management サービス] ページで、作成した API Management インスタンスを選択します。下図のように、[概要] ページで、Status：Onlineとなっていれば本課題はクリアです。念のため、Tier：Developerであることも確認しておきましょう。

課題２．モック応答のAPI(GET/POST)を作成しよう

■目的
モックとは、「モックアップ」の省略表現で、完成後に実際に表示される状態を模した実物そっくりの画像や画面などのことを示します。本課題ではAPIMだけで処理が完結するAPI（≒モック応答のAPI）を作成します。

■実践
下記チュートリアルの内容に沿って実施してください。

チュートリアル - API Management で API の応答の模擬テストを実行する - Azure portal | Microsoft Learn

■ゴール
チュートリアルページの「モック API をテストする」に記載されている内容の通り、テスト呼び出しの送信の結果、HTTP Responseが200 OKになっていれば、本課題はクリアです。

■発展課題
このチュートリアルではGET メソッドのTest call APIを作成していました。
同様にPOSTメソッドのTest call APIを作成して、テスト呼び出しが200 OKになることを確認してください。POSTメソッドでは、GETメソッドでは指定ができなかったリクエストボディにデータを含めて送信することが可能です。その点も確認できるとパーフェクトです。※リクエストボディはどのような値でも問題ありません。

■参考情報
本来APIMはサービス名称の通り、APIを統合管理する為のサービスです。
一般的に各APIのバックエンドには要求を処理する為の別サービスが存在します。（図のApp Service Environment やKubernetes Service が該当）

しかし、このバックエンドを開発する前にAPIMのAPIそのものをテストしたい場合があります。そのような場合にモックAPIを利用します。

Azure Application Gateway と Azure API Management で API を保護する - Azure Architecture Center | Microsoft Learn

課題３．認証キー情報を付与してリクエストしよう

■目的
最後にHTTPヘッダー/URLクエリパラメータについて学習します。
APIMではHTTPヘッダー/URLクエリパラメータを介して認証キーを受け渡しする仕様となっています。この仕様を利用して、HTTPヘッダー/URLクエリパラメータによる情報の受け渡しを学びます。

■実践
課題２ではAzureポータルのAPIの[テスト] タブからHTTPリクエストを送信して、検証しました。
同じことをウェブブラウザから実行してみましょう。EdgeやChromeなど普段利用しているウェブブラウザを起動して、作成したAPIをURL欄に直接入力して実行してください。

作成したAPIのURLがわからないという人は課題２に戻って、AzureポータルのAPIの[テスト] タブからHTTPリクエストを再実行してください。Request URL欄に作成したAPIのURLが表示されています。

どのような結果になりましたか？
以下のエラーメッセージのように401 Access Deniedとなったはずです。
（もし、サブスクリプションキーをHTTPヘッダーもしくはURLクエリパラメータで与える必要があることに気が付いて、200 OKと表示された人はこの課題はクリアです!!）

エラーメッセージ
{ "statusCode": 401, "message": "Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API." }

HTTPヘッダーによる情報の受け渡し
APIにアクセスするための認証キーが必須となる設定（API の[設定] ページで [Subscription required]）が既定で有効化されています。

Azure ポータルからAPIのテストリクエスト送信時には、Azureポータルの機能でHTTPヘッダー情報に認証キー（Ocp-Apim-Subscription-Key）をセットしてリクエストしていました。一方で、Azureポータル以外（ウェブブラウザなど）から実行する場合にはリクエスト時に認証キーを明示的にセットする必要があります。課題３の冒頭でウェブブラウザからAPIにリクエストを送信した際には、この認証キーを設定しなかったので、401 Access Deniedの結果となりました。

このようにHTTPではリクエストやレスポンスに付加される情報をHTTPヘッダー情報として受け渡しすることができます。

URLクエリパラメータによる情報の受け渡し

では、最後にHTTPヘッダー以外での情報の受け渡し方法であるURLクエリパラメータを紹介して終わりにします。

課題３の冒頭で実施したのと同様にEdgeやChromeなど普段利用しているウェブブラウザを起動して、作成したAPIをURL欄に直接入力して実行してみましょう。

今回はそこにURLクエリパラメータを付与します。
具体的には以下の通りです。

　下線部：ご自身で作成されたAPIのURLに読み替えてください。
　太字：Azure ポータルからAPIのテストのHTTP RequestもしくはHTTP Responseに32桁の認証キー (Ocp-Apim-Subscription-Key)が記載されています。

ウェブブラウザに入力するURL
https://apim-hello-world.azure-api.net/test?subscription-key=32桁のサブスクリプションキー

無事200 OKの結果となりましたか？認証キーの末尾1文字だけを変更して401になることまで確認できると尚良いかと思います。

以上でHTTPにおける情報の受け渡しに関する実践課題でした。

■参考情報
サブスクリプションキーを使用する | Microsoft Learn

まとめ

この課題をきっかけに複数サービスを組み合わせて、より実践的な課題に取り組むこと（手を動かすこと）が「Azure＋インフラ技術」を学習する上で重要なことだと感じています。参考情報として私のチームで取り組んでいる課題の一部を記載致します。
このブログが皆様の学習のお役に立てば幸いです。

■実践課題で学んだこと
APIMには価格レベルによって機能差異がある。
よく利用されるHTTPメソッドとしてGET/POSTメソッドがあり、用途に応じて使い分ける必要がある。※その他メソッドは本課題では扱っておりません。
APIMではモック応答のAPIを作成できる。
APIMのAPIにリクエストする場合には既定では認証キーが必要。
認証キーは、HTTPヘッダーもしくはURLクエリパラメータで渡すことができる。
既定では認証キー受け渡し時の項目名が異なる。

　HTTPヘッダーで渡す場合、項目名はOcp-Apim-Subscription-Key 　URLクエリパラメータで渡す場合、項目名はsubscription-key

【APIM編】
APIMのバックエンドにFunctionsを配置する
APIMのポリシー開発を行う
APIMの名前付き値をキーコンテナで管理する
APIMにカスタムドメインを設定する

【その他】
Functions（HTTPトリガー、Timerトリガー、Service Busトリガー）を開発する
AzureリソースをARMテンプレートでデプロイする
仮想マシン（Linux、BIND、Apache、Tomcatなど）を構築する

＃興味があればご連絡ください。ご要望があれば、続編を記載します！