文件翻譯的受控識別

發行項
04/09/2024

適用於 Azure 資源的受控識別是一種服務主體，其會建立 Microsoft Entra 身分識別和 Azure 受控資源的特定權限。受控識別提供更安全的方式來授與儲存體資料的存取權，並取代您包含共用存取簽章權杖 (SAS) 與您的來源和目標 URL 的需求。

Screenshot of managed identity flow (RBAC).

您可以使用受控識別，對支援 Microsoft Entra 驗證的任何資源 (包括您自己的應用程式) 授與存取權。
若要授與 Azure 資源的存取權，請使用 Azure 角色型存取控制 (Azure RBAC)，將 Azure 角色指派給受控識別。
在 Azure 中使用受控識別不會產生額外的成本。

重要

使用受控識別時，請勿在 HTTP 要求中包含 SAS 權杖 URL，否則您的要求將會失敗。使用受控識別可取代您包含共用存取簽章權杖 (SAS) 與來源和目標 URL 的需求。
若要使用文件翻譯作業的受控識別，您必須在特定 Azure 地理區域中建立翻譯工具資源，例如美國東部。如果您的翻譯工具資源區域設定為全域，則您無法使用文件翻譯的受控識別。您仍然可以使用共用存取簽章權杖 (SAS) 進行文件翻譯。
文件翻譯僅適用於 S1 標準服務方案， (隨用隨付) 或 D3 大量折扣方案。 請參閱Azure AI 服務定價—翻譯工具。

必要條件

若要開始，您需要：

作用中的 Azure 帳戶—如果沒有，您可以建立免費帳戶。
單一服務翻譯工具 (不是多重服務 Azure AI 服務) 資源，此資源指派至美國西部等地理區域。如需詳細步驟，請參閱建立多服務資源。
使用 Azure 入口網站簡要了解 Azure 角色型存取控制 (Azure RBAC)。
Azure Blob 儲存體帳戶，與翻譯工具資源位於同一區域中。您也需要建立容器，以在儲存體帳戶內儲存和組織 Blob 資料。
如果您的儲存體帳戶位於防火牆後方，您必須啟用下列設定：
1. 前往 Azure 入口網站並登入 Azure 帳戶。
2. 選取儲存體帳戶。
3. 在左窗格中的 [安全性 + 網路] 群組中，選取 [網路]。
4. 在 [防火牆和虛擬網路] 索引標籤中，選取 [從選取的虛擬網路和 IP 位址啟用]。
5. 取消全選核取方塊。
6. 請確定已選取 [Microsoft 網路路由]。
7. 在 [資源執行個體] 區段下，選取 [Microsoft.CognitiveServices/accounts] 作為資源類型，然後選取翻譯工具資源作為執行個體名稱。
8. 確認是否已勾選 [允許受信任服務清單上的 Azure 服務存取此儲存體帳戶] 方塊。如需管理例外狀況的詳細資訊，請參閱設定 Azure 儲存體防火牆和虛擬網路。
9. 選取 [儲存]。
  
  注意
  
  網路變更最多可能需要 5 分鐘的時間才能傳播。
雖然現在允許網路存取，但您的翻譯工具資源仍無法存取儲存體帳戶中的資料。您必須建立受控識別，並將特定存取角色指派給翻譯工具資源。

受控識別指派

有兩種受控識別：系統指派和使用者指派。目前，文件翻譯支援系統指派的受控識別：

系統指派的受控識別會直接在 Azure 服務執行個體上「啟用」。預設不會將其啟用；您必須移至您的資源，並更新身分識別設定。
系統指派的受控識別會在其整個生命週期繫結至您的資源。如果刪除您的資源，則也會刪除受控識別。

在下列步驟中，我們啟用系統指派的受控識別，並授權 Azure Blob 儲存體帳戶可以有限存取翻譯工具資源。

啟用系統指派的受控識別

您必須先將翻譯工具資源存取權授與儲存體帳戶，才能建立、讀取或刪除 Blob。使用系統指派的受控識別啟用翻譯工具資源之後，您可以使用 Azure 角色型存取控制 (Azure RBAC)，為翻譯工具提供 Azure 儲存體容器的存取權。

前往 Azure 入口網站並登入 Azure 帳戶。
選取翻譯工具資源。
在左窗格的 [資源管理] 群組中，選取 [身分識別]。
在 [已指派系統] 索引標籤內，開啟 [狀態]。

重要

使用者指派的受控識別不符合批次謄寫儲存體帳戶情節的需求。務必啟用系統指派的受控識別。
選取 [儲存]。

授與翻譯工具資源的儲存體帳戶存取權

重要

若要指派系統指派的受控識別角色，您需要 Microsoft.Authorization/roleAssignments/write 權限，例如儲存體資源的儲存體範圍中的擁有者或使用者存取管理員。

前往 Azure 入口網站並登入 Azure 帳戶。
選取翻譯工具資源。
在左窗格的 [資源管理] 群組中，選取 [身分識別]。
在 [權限] 下，選取 [Azure 角色指派]：
在開啟的 Azure 角色指派頁面上，從下拉式功能表中選擇您的訂用帳戶，然後選取 [+ 新增角色指派]。
下一步，將 [儲存體 Blob 資料參與者] 角色指派給翻譯工具服務資源。 儲存體 Blob 資料參與者角色會提供翻譯工具 (以系統指派的受控識別表示) 讀取、寫入及刪除 Blob 容器和資料的存取權。在 [新增角色指派] 快顯視窗中，完成如下的欄位，然後選取 [儲存]：

欄位值

範圍 儲存空間。

訂用帳戶 與儲存體資源相關聯的訂用帳戶。

資源 儲存體資源的名稱。

Role 儲存體 Blob 資料參與者。
顯示「已新增角色指派」確認訊息之後，請重新整理頁面以查看新增的角色指派。
如果您沒有立即看到新角色指派，請稍候再次嘗試重新整理頁面。當您指派或移除角色指派時，最多可能需要 30 分鐘的時間，變更才會生效。

欄位	值
範圍	*儲存空間*。
訂用帳戶	*與儲存體資源相關聯的訂用帳戶*。
資源	*儲存體資源的名稱*。
Role	*儲存體 Blob 資料參與者*。

HTTP 要求

非同步批次翻譯要求會透過 POST 要求提交至您的翻譯工具服務端點。
使用受控識別和 Azure RBAC，您將不再需要包含 SAS URL。
如果成功，POST 方法會傳回 202 Accepted 回應碼，且服務會建立批次要求。
已翻譯的文件會出現在您的目標容器中。

標頭

每個文件翻譯 API 要求都會包含下列標頭：

HTTP 標頭	描述
Ocp-Apim-Subscription-Key	必要：此值是翻譯工具或 Azure AI 服務資源的 Azure 金鑰。
內容-類型	必要：指定承載的內容類型。接受的值為 application/json 或 charset=UTF-8。

POST 要求本文

要求 URL 為 POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches。
要求本文是名為 inputs 的 JSON 物件。
inputs 物件包含來源和目標語言配對的 sourceURL 和 targetURL 容器位址。透過系統指派的受控識別，您將使用一般儲存體帳戶 URL (沒有 SAS 或其他新增項目)。格式為 https://<storage_account_name>.blob.core.windows.net/<container_name>。
prefix 和 suffix 欄位 (選擇性) 用來篩選包含資料夾的容器中的文件。
在翻譯文件時，會套用 glossaries 欄位 (選擇性) 的值。
每個目標語言的 targetUrl 都必須是唯一的。

重要

如果目的地中已存在相同名稱的檔案，則工作會失敗。使用受控識別時，請勿在 HTTP 要求中包含 SAS 權杖 URL。否則，要求將會失敗。

翻譯容器中的所有文件

此範例要求本文會參考要翻譯為目的語言之所有文件的來源容器。

如需詳細資訊，請參閱要求參數。

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>"
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>"
                    "language": "fr"
                }
            ]
        }
    ]
}

翻譯容器中的特定文件

此範例要求本文參考要翻譯成兩種目的語言的單一來源文件。

重要

除了先前所述的要求參數之外，您還必須包含 "storageType": "File"。否則，系統會假設來源 URL 位於容器層級。

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>/source-english.docx"
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>/Target-Spanish.docx"
                    "language": "es"
                },
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>/Target-German.docx",
                    "language": "de"
                }
            ]
        }
    ]
}

使用自訂詞彙翻譯容器中的所有文件

此範例要求本文會參考要使用詞彙翻譯為目的語言之所有文件的來源容器。