サブスクリプション キーを使って API を呼び出す

API を発行するときに、ゲートウェイを介してその API にアクセスできるユーザーをある程度制御したいことがよくあります。 サブスクリプション キーを使って、API へのアクセスを制限できます。

ここでは、サブスクリプション キーを使って API をセキュリティで保護する方法を学習します。

サブスクリプションとキー

サブスクリプション キーを使って、自分の API を保護することができます。

サブスクリプション キーは一意の自動生成された文字列で、クライアント要求のヘッダーで渡す必要があります。 このキーは、さまざまな領域にスコープを指定できるサブスクリプションと直接関連します。これにより、アクセス許可とポリシーをきめ細かく制御できます。 3 つの主なサブスクリプションのスコープは次のとおりです。

  • すべての API
  • 1 つの API
  • 成果物

保護された API を呼び出すアプリケーションでは、要求の呼び出しにキーを含める必要があります。

これらのサブスクリプション キーはいつでも再生成できます。たとえば、キーが未承認のユーザーと共有されたおそれがある場合です。

サブスクリプション キー

すべてのサブスクリプションには 2 つのキーがあります。プライマリとセカンダリです。 2 つのキーがあることで、必要に応じてキーを再生成しやすくなります。 たとえば、主キーを変更しつつダウンタイムを回避したい場合は、アプリ内でセカンダリ キーを使います。

サブスクリプションが有効になっている成果物の場合、その成果物内の API を呼び出すときにキーを指定する必要があります。 開発者は、サブスクリプション要求を送信することでキーを取得できます。 これは APIM ワークフローの中核です。

[注] 新しいユーザーを作成し、API にアクセスできるように各自のサブスクリプション キーを付与することは、APIM ワークフローの中核ですが、このモジュールの範囲外です。

サブスクリプション キーを使って API を呼び出す

アプリケーションからサブスクリプションによって保護されている API エンドポイントへの呼び出しを行う場合は、すべての HTTP 要求に有効なキーを含める必要があります。 キーは、要求ヘッダー内で、または URL のクエリ文字列として渡すことができます。

既定のヘッダー名は Ocp-Apim-Subscription-Key で、既定のクエリ文字列は subscription-key です。

API の呼び出しをテストするには、開発者ポータルか、コマンドライン ツール (curl など) を使えます。 サブスクリプション キーのヘッダーを示す、開発者ポータルを使った GET 要求の例を次に示します。

開発者ポータルから API を呼び出す

curl を使って要求ヘッダーでキーを渡す方法を次に示します。

curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path

URL 内でクエリ文字列としてキーを渡す curl コマンドの例を次に示します。

curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>

ヘッダーで、または URL のクエリ文字列として、キーが渡されなかった場合は、API ゲートウェイから [401 アクセスは拒否されました] 応答が返されます。