共用方式為

使用媒體服務 v3 API 開發

  • 發行項

媒體服務標誌 v3

警告

Azure 媒體服務將於 2024 年 6 月 30 日淘汰。 如需詳細資訊，請參閱 AMS淘汰指南。

身為開發人員，您可以使用 (.NET、Python、Node.js、Java 和 Go) 的用戶端連結庫，讓您與 REST API 互動，輕鬆地建立、管理及維護自定義媒體工作流程。 媒體服務 v3 API 以 OpenAPI 規格 (先前稱為 Swagger) 作為基礎。

本文討論使用媒體服務 v3 開發時，適用於實體與 API 的規則。

警告

因為您需要實作完整的 Azure 資源管理重試邏輯，並了解如何管理 Azure 資源管理 API 中長時間執行的作業，所以不建議您嘗試將媒體服務的 REST API 直接包裝至自己的程式庫程式碼。 用戶端 SDK 會處理各種語言的 SDK- .NET、Java、TypeScript、Python 等等，並自動減少您遇到重試邏輯或失敗 API 呼叫問題的機會。 用戶端 SDK 已經會為您處理所有工作。

存取 Azure 媒體服務 API

在獲得存取媒體服務資源和媒體服務 API 的授權之前，您必須先進行驗證。 媒體服務支援 Azure Active Directory (Azure AD) 型驗證。 兩種常見的驗證選項為：

  • 服務主體驗證：用以驗證服務 (例如：Web Apps、函數應用程式、Logic Apps、API 與微服務)。 通常使用這種驗證方法的應用程式有執行精靈服務、中介層服務或排程的工作的應用程式。 例如，Web Apps 應該一律有連線到具有服務主體之媒體服務的中介層。
  • 使用者驗證：用以驗證使用應用程式與媒體服務資源互動的人員。 互動式應用程式應該先提示使用者輸入使用者的認證。 例如，授權的使用者用來監控編碼工作或即時串流的管理主控台應用程式。

媒體服務 API 需要讓提出 REST API 要求的使用者或應用程式能夠存取媒體服務帳戶資源，並使用參與者或擁有者角色。 您可以使用讀者角色來存取 API，但只能使用 Get 或 List 作業。 如需詳細資訊，請參閱媒體服務帳戶的 Azure 角色型存取控制 (Azure RBAC)。

請考慮使用 Azure 資源受控識別，透過 Azure Resource Manager 存取媒體服務 API，而不是建立服務主體。 若要深入了解 Azure 資源受控識別，請參閱什麼是 Azure 資源受控識別。

Azure AD 服務主體

Azure AD 應用程式和服務主體應位於相同的租用戶。 建立應用程式之後，請將應用程式參與者或擁有者角色存取權授與媒體服務帳戶。

若不確定自己是否有權建立 Azure AD 應用程式，請參閱必要權限。

下圖中，數字代表依時間順序排列的要求流程：

從 Web API 使用 AAD 進行中介層應用程式驗證

  1. 中介層應用程式要求具有下列參數的 Azure AD 存取權杖：

    • Azure AD 租用戶端點。
    • 媒體服務資源 URI。
    • REST 媒體服務的資源 URI。
    • Azure AD 應用程式值：用戶端識別碼與用戶端密碼。

    若要取得所有需要的值，請參閱存取 Azure 媒體服務 API。

  2. Azure AD 存取權杖會傳送至中介層。

  3. 中介層使用該 Azure AD 權杖傳送要求至 Azure 媒體 REST API。

  4. 媒體服務回傳資料給中介層。

範例

請參閱下列範例，了解如何使用 Azure AD 服務主體連線：

命名慣例

Azure 媒體服務 v3 資源名稱 (例如資產、作業、轉換) 會受到 Azure Resource Manager 命名規則的約束。 根據 Azure Resource Manager，資源名稱永遠是唯一的。 因此，您可以對資源名稱使用任何唯一識別碼字串 (例如，GUID)。

媒體服務資源名稱不能包含：''、'<>'、'%'、'&'、'：'、'\'、'？'、'/'、'*'、'+'、'.'、單引號字元或任何控制字元。 允許所有其他字元。 資源名稱的長度上限是 260 個字元。

如需 Azure Resource Manager 命名的詳細資訊，請參閱命名需求與命名慣例。

資產中的檔案/Blob 名稱

資產中的檔案/Blob 名稱必須遵循 Blob 名稱需求與 NTFS 名稱需求。 之所以會有這些需求，是因為檔案會從 Blob 儲存體複製到本機 NTFS 磁碟加以處理。

長期執行作業

Azure 媒體服務 Swagger 檔案中以 x-ms-long-running-operation 標示的作業，是長期執行作業。

如需如何追蹤非同步 Azure 作業的詳細資訊，請參閱非同步作業。

媒體服務具有下列長期執行作業：

成功提交長期執行作業時，您會收到「201 已接受」訊息，而且必須使用傳回的作業識別碼來輪詢作業完成度。

追蹤非同步 Azure 作業一文會深入說明如何透過回應中傳回的值，追蹤非同步 Azure 作業的狀態。

僅支援指定即時事件或其任何相關聯即時輸出的一個長期執行作業。 啟動之後，長期執行作業必須先完成，才能在相同的即時事件或任何相關聯的即時輸出上，啟動後續的長期執行作業。 針對具有多個即時輸出的即時事件，您必須先等待一個即時輸出的長期執行作業完成，才能觸發另一個即時輸出的長期執行作業。

SDK

注意

Azure 媒體服務 v3 SDK 不保證是安全的執行緒。 在開發多執行緒應用程式時，您應新增本身的執行緒同步邏輯以保護用戶端，或每個執行緒都使用新的 AzureMediaServicesClient 物件。 您也應留意程式碼提供給用戶端 (例如 .NET 中的 HttpClient 執行個體) 的選擇性物件所引起的多執行緒處理問題。

SDK 參考
.NET SDK .NET 參考
Java SDK Java 參考
Python SDK Python 參考
Node.js SDK Node.js 參考
Go SDK Go 參考

另請參閱

Azure 媒體服務總管

Azure 媒體服務總管 (AMSE) 是想要了解媒體服務的 Windows 客戶可用的工具。 AMSE 是 Winforms/C# 應用程式，可利用媒體服務上傳、下載、編碼、串流 VOD 和即時內容。 AMSE 工具適用於想要測試媒體服務，而不要撰寫任何程式碼的用戶端。 AMSE 程式碼會當作資源提供給想要使用媒體服務開發的客戶。

AMSE 是一個開放原始碼專案，由社群提供支援 (可將問題回報給 https://github.com/Azure/Azure-Media-Services-Explorer/issues)。 此專案採用了 Microsoft 開放原始碼管理辦法。 如需詳細資訊，請參閱管理辦法常見問題集，如有其他問題或意見，請連絡 opencode@microsoft.com。

媒體服務實體的篩選、排序、分頁

請參閱 Azure 媒體服務實體的篩選、排序、分頁。

取得說明及支援

您可以連絡媒體服務並提出問題，或遵循下列其中一種方法來追蹤我們的更新：