教學課程:使用 Azure AI 影片索引器 API

重要

由於 Azure 媒體服務 淘汰公告,Azure AI 影片索引器會宣告 Azure AI 影片索引器功能調整。 請參閱 Azure 媒體服務 (AMS) 淘汰 的相關變更,以瞭解 Azure AI 影片索引器帳戶的意義。 請參閱準備AMS淘汰:VI更新和移轉指南

Azure AI 影片索引器會將 Microsoft 所提供的各種音訊和視訊人工智慧 (AI) 技術合併成一項整合式服務,讓開發更簡單。 API 的設計目的是讓開發人員專注於使用媒體 AI 技術,而不必擔心雲端平臺的規模、全球觸達、可用性和可靠性。 您可以使用 API 來上傳檔案、取得詳細的影片深入解析、取得可內嵌深入解析和播放程式小工具的 URL 等等。

當您第一次流覽 Azure AI 影片索引器 網站時,系統會自動為您建立試用帳戶。 使用試用帳戶時,您會取得一些免費的索引分鐘數。 您稍後可以新增付費帳戶。 使用付費選項時,您會支付已編製索引的分鐘數。 如需可用帳戶的詳細數據(試用版和付費選項),請參閱 Azure AI 影片索引器帳戶類型

本文說明開發人員如何利用 Azure AI 影片索引器 API

必要條件

開始之前,請參閱本文稍後的<建議>一節。

訂閱 API

  1. 登入 Azure AI 影片索引器 API 開發人員入口網站

    重要

    • 您必須使用註冊 Azure AI 影片索引器時所使用的相同提供者。
    • 個人Google和 Microsoft (Outlook/Live) 帳戶只能用於試用帳戶。 聯機至 Azure 的帳戶需要 Entra 識別碼。
    • 每個電子郵件只能有一個使用中的帳戶。 如果用戶嘗試使用 user@gmail.com 來登入 LinkedIn,稍後 user@gmail.com 使用 Google 登入,則後者會顯示錯誤頁面,指出用戶已經存在。

    Sign in to the Azure AI Video Indexer API developer portal

  2. 訂閱。

    選取 [產品] 索引標籤。然後,選取 [授權] 並訂閱。

    注意

    新用戶會自動訂閱授權。

    訂閱之後,您可以在 [產品 -> 配置檔] 底下找到您的訂用帳戶。 在 [訂用帳戶] 區段中,您會發現主要和次要密鑰。 金鑰應受到保護。 金鑰只能由您的伺服器程式代碼使用。 它們不應該在用戶端上使用(.js、.html等等)。

    Subscription and keys in the Azure AI Video Indexer API developer portal

Azure AI 影片索引器使用者可以使用單一訂用帳戶密鑰來連線到多個 Azure AI 影片索引器帳戶。

使用授權 API 取得存取令牌

訂閱授權 API 之後,您可以取得存取令牌。 這些存取令牌可用來向 Operations API 進行驗證。

對 Operations API 的每個呼叫都應該與存取令牌相關聯,並符合呼叫的授權範圍。

  • 用戶層級:用戶層級存取令牌可讓您在 用戶 層級上執行作業。 例如,取得相關聯的帳戶。
  • 帳戶層級:帳戶層級存取令牌可讓您在 帳戶 層級或 視訊 層級上執行作業。 例如,上傳影片、列出所有影片、取得影片深入解析等等。
  • 影片層級:視訊層級存取令牌可讓您在特定視訊執行作業。 例如,取得影片深入解析、下載 標題、取得小工具等等。

您可以透過兩種方式控制權杖的權限等級:

  • 針對帳戶令牌,您可以使用取得具有許可權 API 的帳戶存取令牌,並指定許可權類型(讀者/參與者/MyAccessManager/擁有者)。
  • 針對所有類型的令牌(包括 帳戶 令牌),您可以指定 allowEdit=true/falsefalse 相當於 讀取者 許可權(只讀),而 true 相當於 參與者 許可權(讀寫)。

針對大部分的伺服器對伺服器案例,您可能會使用相同的 帳戶 令牌,因為它同時涵蓋 帳戶 作業和 視訊 作業。 不過,如果您打算對 Azure AI 影片索引器進行用戶端呼叫(例如,從 JavaScript),您會想要使用 影片 存取令牌來防止用戶端存取整個帳戶。 這也是在用戶端中內嵌 Azure AI 影片索引器用戶端程式代碼(例如,使用 Get Insights Widget 或 Get Player Widget)時的原因,您必須提供影片存取令牌。

為了簡化工作,您可以使用授權 API> GetAccounts 來取得您的帳戶,而不需要先取得使用者令牌。 您也可以要求取得具有有效令牌的帳戶,讓您略過額外的呼叫以取得帳戶令牌。

存取令牌會在 1 小時後到期。 使用 Operations API 之前,請確定您的存取令牌有效。 如果到期,請再次呼叫授權 API 以取得新的存取令牌。

您已準備好開始與 API 整合。 尋找 每個 Azure AI 影片索引器 REST API 的詳細描述。

作業 API 呼叫

所有作業 API 呼叫都需要帳戶標識子參數。 帳戶標識碼是一種 GUID,可透過下列其中一種方式取得:

  • 使用 Azure AI 影片索引器網站來取得帳戶識別碼:

    1. 流覽至 Azure AI 影片索引器 網站並登入。

    2. 流覽至 設定 頁面。

    3. 複製帳戶標識碼。

      Azure AI Video Indexer settings and account ID

  • 使用 Azure AI 影片索引器開發人員入口網站 ,以程式設計方式取得帳戶標識碼。

    使用取得帳戶 API。

    提示

    您可以藉由定義 generateAccessTokens=true來產生帳戶的存取令牌。

  • 從您帳戶中播放器頁面的 URL 取得帳戶標識碼。

    當您觀看影片時,標識碼會出現在 accounts 區段之後和區段之前 videos

    https://www.videoindexer.ai/accounts/00000000-f324-4385-b142-f77dacb0a368/videos/d45bf160b5/
    

建議

本節列出使用 Azure AI 影片索引器 API 時的一些建議。

正在上傳

  • 如果您打算上傳影片,建議您將檔案放在一些公用網路位置(例如,Azure Blob 儲存體 帳戶)。 取得影片的連結,並提供 URL 作為上傳檔案參數。

    提供給 Azure AI 影片索引器的 URL 必須指向媒體(音訊或視訊)檔案。 URL (或 SAS URL) 的簡單驗證是將它貼到瀏覽器中,如果檔案開始播放/下載,可能是一個很好的 URL。 如果瀏覽器正在轉譯某些視覺效果,它可能不是檔案的連結,而是 HTML 頁面的連結。 當您使用 API 上傳影片時,您有下列選項:

  • 從 URL 上傳您的影片(慣用)。
  • 以位元組陣陣的形式在要求本文中傳送影片檔案。
  • API 要求限制為每秒 10 個要求,每分鐘最多 120 個要求。

取得 JSON 輸出

  • 當您呼叫取得指定影片影片深入解析的 API 時,您會取得詳細的 JSON 輸出作為響應內容。 請參閱本文中傳回 JSON 的詳細數據

  • API 所產生的 JSON 輸出包含 InsightsSummarizedInsights 元素。 我們強烈建議使用 Insights 和 不使用 SummarizedInsights (這是為了回溯相容性而存在)。

  • 不建議您直接從 artifacts 資料夾使用數據,以供生產之用。 成品是編製索引程式的中繼輸出。 它們基本上是分析影片的各種 AI 引擎的原始輸出;成品架構可能會隨著時間而變更。

    建議您使用取得影片索引 API,如取得 API 所產生的深入解析和成品中所述,而不是Get-Video-Artifact-Download-Url

程式碼範例

如需程式代碼範例, 請參閱範例存放庫