Media Services v3 API を使用して開発する
警告
Azure Media Services は、2024 年 6 月 30 日に廃止されます。 詳細については、 AMS 廃止ガイドを参照してください。
開発者は、REST API を操作できる (.NET、Python、Node.js、Java、Go 用の) クライアント ライブラリを使用して、カスタム メディア ワークフローを簡単に作成、管理、メンテナンスできます。 Media Services v3 API は、OpenAPI 仕様 (旧称 Swagger) に基づいています。
この記事では、Media Services v3 を使用して開発を行うときにエンティティと API に適用される規則について説明します。
警告
Media Services の REST API を、ご自身のライブラリ コードに直接ラップすることはお勧めしません。これを運用環境で適切に行うには、Azure Resource Management の完全な再試行ロジックを実装し、Azure Resource Management API 内で実行時間の長い操作を管理する方法を理解する必要があるためです。 これは、さまざまな言語 (.NET、Java、TypeScript、Python など) のクライアント SDK によって自動的に処理されるため、再試行ロジックや失敗した API 呼び出しに関する問題が発生する可能性が少なくなっています。 この処理は、クライアント SDK によって既にすべて実行されています。
Azure Media Services API へのアクセス
Media Services リソースと Media Services API へのアクセスが承認されるには、まず認証を受ける必要があります。 Media Services では、Azure Active Directory (Azure AD) ベースの認証がサポートされています。 2 つの一般的な認証オプションがあります。
- サービス プリンシパル認証: サービスの認証に使用されます (例: Web アプリ、関数アプリ、ロジック アプリ、API、マイクロサービス)。 この認証方法がよく使用されるアプリケーションは、デーモン サービス、中間層サービス、またはスケジュールされたジョブを実行するアプリです。 たとえば、Web アプリの場合、サービス プリンシパルで Media Services に接続する中間層が常にあるはずです。
- ユーザー認証: Media Services リソースを操作するアプリを使用しているユーザーを認証するために使用されます。 対話型アプリでは、最初に、ユーザーにユーザー資格情報の入力を求める必要があります。 例として、承認済みユーザーがエンコード ジョブまたはライブ ストリーミングを監視するために使用する管理コンソール アプリがあります。
Media Services API では、REST API 要求を行うユーザーまたはアプリは、Media Services アカウント リソースへのアクセス権を持ち、共同作成者または所有者のロールを使用することが必要です。 閲覧者ロールで API にアクセスすることはできますが、使用できる操作は Get または List だけです。 詳細については、「Media Services アカウント用のロールベースのアクセス制御 (RBAC)」を参照してください。
サービス プリンシパルを作成する代わりに、Azure リソースに対するマネージド ID を使い、Azure Resource Manager で Media Services API にアクセスすることを検討してください。 Azure リソースに対するマネージド ID の詳細については、「Azure リソースのマネージド ID とは」を参照してください。
Azure AD のサービス プリンシパル
Azure AD アプリとサービス プリンシパルは同じテナントに存在する必要があります。 アプリを作成した後、アプリの共同作成者または所有者ロールのアクセス権を、Media Services アカウントに付与します。
Azure AD アプリを作成するためのアクセス許可を自分が持っているかどうかわからない場合は、「必要なアクセス許可」を参照してください。
次の図の番号は、要求のフローを時系列で表したものです。
中間層アプリが、次のパラメーターが含まれた Azure AD アクセス トークンを要求します。
- Azure AD テナント エンドポイント。
- Media Services リソース URI。
- REST Media Services のリソース URI。
- Azure AD アプリの値: クライアント ID とクライアント シークレット。
必要な値をすべて取得するには、Azure Media Services API にアクセスする方法に関する記事を参照してください。
Azure AD アクセス トークンが中間層アプリに送信されます。
中間層アプリが、Azure AD トークンを使用して要求を Azure Media REST API に送信します。
Media Services からデータが中間層アプリに返されます。
サンプル
Azure AD サービス プリンシパルを使った接続方法を示す次のサンプルを参照してください。
名前付け規則
Azure Media Services v3 のリソース名 (アセット、ジョブ、変換など) には、Azure Resource Manager の名前付け規則が適用されます。 Azure Resource Manager に従って、リソース名は常に一意となります。 そのため、リソース名には一意識別子の文字列 (GUID など) を使用できます。
Media Services リソース名には、'<'、'>'、'%'、'&'、':'、'\'、'?'、'/'、'*'、'+'、'.'、単一引用符文字、またはコントロール文字を含めることはできません。 それ以外の文字は使用できます。 リソース名の最大文字数は 260 文字です。
Azure Resource Manager の名前付けの詳細については、名前付けの要件に関するページおよび名前付け規則に関するページをご覧ください。
資産内のファイルまたは BLOB の名前
アセット内のファイルまたは BLOB の名前は、BLOB 名の要件とNTFS 名の要件の両方に従っている必要があります。 これらの要件は、ファイルが BLOB ストレージからローカルの NTFS ディスクにコピーされて処理できるようにするためのものです。
長時間にわたって実行される操作
Azure Media Services の Swagger ファイルに x-ms-long-running-operation とマークされた操作は長期操作です。
非同期の Azure 操作を追跡する方法について詳しくは、非同期操作に関するセクションを参照してください。
Media Services には、次のような長期操作があります。
-
イベントの停止時に、関連付けられているライブ出力をすべて削除するには
removeOutputsOnStopパラメーターを使用します。
長い操作の送信に成功すると、"201 Created" を受け取ります。返された操作 ID を使用して、操作の完了をポーリングする必要があります。
「非同期 Azure 操作の追跡」の記事では、応答で返される値を通じて非同期 Azure 操作の状態を追跡する方法について説明します。
実行時間の長い操作は、特定のライブ イベントまたはそれに関連付けられているライブ出力に対して 1 つだけサポートされます。 実行時間の長い操作が開始したら、それが完了してからでないと、同じ LiveEvent または関連付けられているライブ出力に対して、実行時間の長い操作を続けて開始できません。 複数のライブ出力があるライブ イベントの場合は、あるライブ出力に対して長時間実行されている操作の完了を待ってから、別のライブ出力に対して長時間実行される操作をトリガーする必要があります。
SDK
注意
Azure Media Services v3 SDK は、スレッドセーフである保証はありません。 マルチスレッドのアプリを開発するときは、独自のスレッド同期ロジックを追加してクライアントを保護するか、スレッドごとに新しい AzureMediaServicesClient オブジェクトを使用する必要があります。 .NET の HttpClient インスタンスなど、コード内の任意のオブジェクトによってクライアントにもたらされるマルチスレッドの問題にも注意を払う必要があります。
| SDK | リファレンス |
|---|---|
| .NET SDK | .NET リファレンス |
| Java SDK | Java リファレンス |
| Python SDK | Python リファレンス |
| Node.js SDK | Node.js リファレンス |
| Go SDK | Go リファレンス |
関連項目
Azure Media Services Explorer
Azure Media Services Explorer (AMSE) は、Media Services について学習したい Windows ユーザーが使用できるツールです。 AMSE は、Media Services で VOD およびライブ コンテンツをアップロード、ダウンロード、エンコード、ストリーミングする Winforms/C# アプリケーションです。 AMSE ツールは、コードを記述しないで Media Services をテストしたいクライアント用です。 AMSE コードは、Media Services による開発を希望するお客様用のリソースとして提供されています。
AMSE はオープン ソース プロジェクトであり、サポートはコミュニティによって提供されます (問題は https://github.com/Azure/Azure-Media-Services-Explorer/issues に報告できます)。 このプロジェクトは、「Microsoft のオープン ソースの倫理規定」を採用しています。 詳しくは、倫理規定についてよくある質問に関する記事を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。
Media Services エンティティのフィルター処理、順序付け、ページング
Azure Media Services エンティティのフィルター処理、順序付け、ページングに関するページを参照してください。
ヘルプとサポート
Media Services に質問がある場合は、次のいずれかの方法で更新プログラムに従ってください。
- Q & A
- Stack Overflow。 質問に タグを付け、 を使用します
azure-media-services。 - @MSFTAzureMedia するか 、@AzureSupport を使用してサポートを要求します。
- Azure portalからサポート チケットを開きます。