Azure AD 認証を使用して REST で Media Services API にアクセスする

Media Services ロゴ


警告

2024 年 2 月 29 日までに Azure Media Services REST API と SDK を v3 に更新してください。 Azure Media Services REST API と .NET および Java 向けクライアント SDK のバージョン 3 では、バージョン 2 より機能が増えています。 Azure Media Services REST API と .NET および Java 向けクライアント SDK のバージョン 2 は廃止となります。

必要な操作: ワークロードの中断を最小限に抑えるために、移行ガイドを参照して、2024 年 2 月 29 日までにコードをバージョン 2 の API と SDK からバージョン 3 の API と SDK に移行してください。 2024 年 2 月 29 日以降、Azure Media Services では、"バージョン 2 REST API および ARM アカウント管理 API バージョン 2015-10-01 でのトラフィックや、バージョン 2 .NET クライアント SDK からのトラフィックを受け取らなくなります。これには、バージョン 2 API を呼び出すことがあるサード パーティのオープンソース クライアント SDK がすべて含まれます。"Media Services v3 の概要に関するページを始めとして、最新バージョンについて確認してください。

Azure Media Services で Azure AD Authentication を使用する場合は、次の 2 つの方法のいずれかで認証できます。

  • ユーザー認証: Azure Media Services リソースを操作するアプリを使用しているユーザーが認証を受けます。 ユーザーは最初にその操作アプリケーションから資格情報の入力を求められます。 たとえば、承認済みユーザーがエンコード ジョブまたはライブ ストリーミングを監視するために使用する管理コンソール アプリなどです。
  • サービス プリンシパルの認証: サービスを認証します。 この認証方法がよく使用されるアプリケーションは、デーモン サービス、中間層サービス、またはスケジュールされたジョブを実行するアプリ (例: Web アプリ、関数アプリ、ロジック アプリ、API、マイクロサービス) です。

このチュートリアルでは、Azure AD サービス プリンシパル認証を使用して、REST で AMS API にアクセスする方法を説明します。

このチュートリアルでは、以下の内容を学習します。

  • Azure Portal から認証情報を取得する
  • Postman を使用してアクセス トークンを取得する
  • アクセス トークンを使用して Assets API をテストする

重要

現在 Media Services では、Azure Access Control Service 認証モデルがサポートされています。 ただし、Access Control 認証は 2018 年 6 月 1 日に非推奨となる予定です。 できるだけ早く Azure AD 認証モデルに移行することをお勧めします。

前提条件

Azure Portal から認証情報を取得する

概要

Media Services API にアクセスするには、以下のデータ ポイントを収集する必要があります。

設定 説明
Azure Active Directory テナント ドメイン microsoft.onmicrosoft.com セキュリティ トークン サービス (STS) エンドポイントとしての Azure AD は、https://login.microsoftonline.com/{your-ad-tenant-name.onmicrosoft.com}/oauth2/token という形式で作成されます。 Azure AD は、リソース (アクセス トークン) にアクセスするために JWT を発行します。
REST API エンドポイント https://amshelloworld.restv2.westus.media.azure.net/api/ これは、アプリケーションのすべての Media Services REST API 呼び出しの呼び出し先エンドポイントです。
クライアント ID (アプリケーション ID) f7fbbb29-a02d-4d91-bbc6-59a2579259d2 Azure AD アプリケーション (クライアント) ID。 アクセス トークンを取得するには、クライアント ID が必要です。
クライアント シークレット +mUERiNzVMoJGggD6aV1etzFGa1n6KeSlLjIq+Dbim0= Azure AD アプリケーション キー (クライアント シークレット)。 アクセス トークンを取得するには、クライアント シークレットが必要です。

Azure Portal から Azure Active Directory 認証情報を取得する

情報を取得するには、次の手順を実行します。

  1. Azure Portal にログインします。

  2. AMS インスタンスに移動します。

  3. [API アクセス] を選択します。

  4. [サービス プリンシパルを使って Azure Media Services API に接続する] をクリックします。

    [Media Services] メニューで [API アクセス] が選択され、右側のウィンドウで [サービス プリンシパルを使って Azure Media Services API に接続する] が選択されていることを示すスクリーンショット。

  5. 既存の Azure AD アプリケーションを選択するか、新しいアプリケーションを作成します (後述します)。

    注意

    Azure Media REST 要求を成功させるには、呼び出すユーザーに、アクセスしたい Media Services アカウントの共同作成者ロールまたは所有者ロールが付与されている必要があります。 "リモート サーバーがエラーを返しました: (401) Unauthorized" という例外を受け取る場合は、「アクセス制御」を参照してください。

    新しい AD アプリケーションを作成する場合は、次の手順を実行します。

    1. [新規作成] をクリックします。

    2. 名前を入力します。

    3. [新規作成] をもう一度クリックします。

    4. [保存] をクリックします。

      [新規作成] ダイアログを示すスクリーンショット。[アプリの作成] テキスト ボックスが強調表示され、[保存] ボタンが選択されています。

      ページに新しいアプリケーションが表示されます。

  6. クライアント ID (アプリケーション ID) を取得します。

    1. アプリケーションを選択します。

    2. 右側のウィンドウからクライアント ID を取得します。

      [Azure AD アプリ] と [アプリケーションの管理] が選択され、右側のウィンドウで [クライアント ID] が強調表示されていることを示すスクリーンショット。

  7. アプリケーションのキー (クライアント シークレット) を取得します。

    1. [アプリケーションの管理] ボタンをクリックします (クライアント ID の情報は [アプリケーション ID] の下に表示されます)。

    2. [キー] をクリックします。

      [アプリケーションの管理] ボタンが選択され、中央のウィンドウで [アプリケーション ID] が強調表示され、右側のウィンドウでは [キー] が選択されていることを示すスクリーンショット。

    3. [説明][有効期限] に入力し、 [保存] をクリックしてアプリケーション キー (クライアント シークレット) を生成します。

      [保存] ボタンをクリックすると、キー値が表示されます。 ブレードから離れる前に、キー値をコピーします。

    API アクセス

AD 接続パラメーターの値を web.config ファイルまたは app.config ファイルに追加して、後でコードに使用することができます。

重要

クライアント キーは重要なシークレットであり、キー コンテナーで適切に保護するか、実稼働環境で暗号化する必要があります。

Postman を使用してアクセス トークンを取得する

このセクションでは、Postman を使用して JWT ベアラー トークン (アクセス トークン) を返す REST API を実行する方法を示します。 Media Services REST API を呼び出すには、呼び出しに "Authorization" ヘッダーを追加し、各呼び出しに "Bearer your_access_token" という値を追加する必要があります (このチュートリアルの次のセクションを参照してください)。 

  1. Postman を開きます。

  2. [POST] を選択します。

  3. 次のようにテナント名の末尾に .onmicrosoft.com を指定し、URL の末尾に oauth2/token を指定して、テナント名を含む URL を入力します。

    https://login.microsoftonline.com/{your-aad-tenant-name.onmicrosoft.com}/oauth2/token

  4. [Headers]\(ヘッダー\) タブを選択します。

  5. "Key/Value"(キー/値) データ グリッドを使用して [Headers]\(ヘッダー\) 情報を入力します。

    [ヘッダー] タブと [一括編集] アクションが選択されていることを示すスクリーンショット。

    または、Postman ウィンドウの右側にある [Bulk Edit]\(一括編集\) リンクをクリックし、次のコードを貼り付けます。

    Content-Type:application/x-www-form-urlencoded
    Keep-Alive:true
    
  6. [Body]\(本文\) タブをクリックします。

  7. "Key/Value"(キー/値) データ グリッドを使用して本文情報を入力します (クライアント ID とシークレット値を置き換えます)。

    データ グリッド

    または、Postman ウィンドウの右側にある [Bulk Edit]\(一括編集\) リンクをクリックし、次の本文を貼り付けます (クライアント ID とシークレット値を置き換えます)。

    grant_type:client_credentials
    client_id:{Your Client ID that you got from your Azure AD Application}
    client_secret:{Your client secret that you got from your Azure AD Application's Keys}
    resource:https://rest.media.azure.net
    
  8. [送信] をクリックします。

    [投稿] テキスト ボックス、[ヘッダー] タブと [本文] タブ、[access_token] が強調表示され、[送信] が検出されていることを示すスクリーンショット。

返される応答には、すべての AMS API にアクセスするために必要なアクセス トークンが含まれています。

アクセス トークンを使用して Assets API をテストする

このセクションでは、Postman を使用して Assets API にアクセスする方法について説明します。

  1. Postman を開きます。

  2. [GET] を選択します。

  3. REST API エンドポイントを貼り付けます (例: https://amshelloworld.restv2.westus.media.azure.net/api/Assets)。

  4. [Authorization]\(承認\) タブを選択します。

  5. [Bearer Token]\(ベアラー トークン\) を選択します。

  6. 前のセクションで作成したトークンを貼り付けます。

    トークンを取得する

    Note

    Postman UX は Mac と PC で異なる可能性があります。 Mac バージョンの [Authentication]\(認証\) セクション ドロップダウンに [Bearer Token]\(ベアラー トークン\) オプションがない場合は、Mac クライアントで Authorization ヘッダーを手動で追加する必要があります。

    Auth ヘッダー

  7. [Headers]\(ヘッダー\) を選択します。

  8. Postman ウィンドウの右側にある [Bulk Edit]\(一括編集\) リンクをクリックします。

  9. 次のヘッダーを貼り付けます。

    x-ms-version:2.19
    Accept:application/json
    Content-Type:application/json
    DataServiceVersion:3.0
    MaxDataServiceVersion:3.0
    
  10. [送信] をクリックします。

返される応答には、アカウント内の資産が含まれています。