用于文档翻译的托管标识

项目
09/09/2024

Azure 资源托管标识是一种服务主体，可为 Azure 托管资源创建 Microsoft Entra 标识和特定权限。托管标识是授予存储数据访问权限的一种更安全的方式，取代了在源和目标 URL 中包含共享访问签名令牌 (SAS) 的要求。

托管标识流的屏幕截图 (RBAC)。

可使用托管标识向支持 Microsoft Entra 身份验证的任何资源（包括你自己的应用程序）授予访问权限。
若要授予对 Azure 资源的访问权限，请使用 Azure 基于角色的访问控制 (Azure RBAC) 为托管标识分配 Azure 角色。
在 Azure 中使用托管标识不会增加成本。

重要

使用托管标识时，请勿在 HTTP 请求中包含 SAS 令牌 URL - 请求将失败。使用托管标识替换了将共享访问签名令牌 (SAS) 包含在源和目标 URL 中的要求。
若要将托管标识用于文档翻译操作，必须在特定的 Azure 地理区域（例如“中国北部”）中创建翻译器资源。如果将翻译器资源区域设置为“全局”，则无法将托管标识用于文档翻译。你仍可使用共享访问签名 (SAS) 令牌进行文档翻译。
S1 标准服务计划（即用即付）与 C2、C3、C4 和 D3 批量折扣计划支持文档翻译。请参阅 Azure AI 服务定价 - 翻译工具。

先决条件

要开始，需要：

有效的 Azure 帐户；如果没有帐户，可以创建一个试用帐户。
分配到某个地理区域（例如中国北部）的单服务翻译器（不是多服务 Azure AI 服务）资源。有关详细步骤，请参阅“创建 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 Blob 存储帐户的有限访问权限。

启用系统分配的托管标识

你必须先向翻译器资源授予对存储帐户的访问权限，然后才能创建、读取或删除 blob。使用系统分配的托管标识启用了翻译器资源后，可使用 Azure 基于角色的访问控制 (Azure RBAC) 向翻译器提供对 Azure 存储容器的访问权限。

转到 Azure 门户并登录 Azure 帐户。
选择翻译器资源。
在左窗格的“资源管理”组中，选择“标识”。
在“系统分配”选项卡中，打开“状态”切换开关。

重要

用户分配的托管标识不符合批量听录存储帐户方案的要求。请确保启用系统分配的托管标识。
选择“保存”。

为翻译器资源授予存储帐户访问权限

重要

若要分配系统分配的托管标识角色，需要 Microsoft.Authorization/roleAssignments/write 权限，例如存储资源的存储范围的所有者或用户访问管理员。

转到 Azure 门户并登录 Azure 帐户。
选择翻译器资源。
在左窗格的“资源管理”组中，选择“标识”。
在“权限”下，选择“Azure 角色分配” ：
在打开的“Azure 角色分配”页面上，从下拉菜单中选择订阅，然后选择“+ 添加角色分配”。
接下来，向翻译器服务资源分配"存储 Blob 数据参与者" 角色。 “存储 Blob 数据参与者”角色向翻译器（由系统分配的托管标识表示）授予对 Blob 容器和数据的读取、写入和删除权限。在“添加角色分配”弹出窗口中，按如下所示填写字段，然后选择“保存” ：

字段值

范围存储。

订阅与存储资源关联的订阅。

资源存储资源的名称。

角色存储 Blob 数据参与者。
显示“已添加角色分配”确认消息后，请刷新页面以查看添加的角色分配。
如果没有立即看到新的角色分配，请稍候，然后尝试再次刷新页面。分配角色或删除角色分配时，最长可能需要 30 分钟更改才能生效。

字段	值
范围	存储。
订阅	与存储资源关联的订阅。
资源	存储资源的名称。
角色	存储 Blob 数据参与者。

HTTP 请求

异步批量翻译请求将通过 POST 请求提交到翻译器服务终结点。
使用托管标识和 Azure RBAC，你不再需要包含 SAS URL。
如果成功，POST 方法将返回 202 Accepted 响应代码，并且服务将创建批处理请求。
经过翻译的文档将会显示在目标容器中。

标头

每个文档翻译 API 请求均包含以下标头：

HTTP 标头	说明
Ocp-Apim-Subscription-Key	必需：该值是翻译或 Azure AI 服务资源的 Azure 密钥。
Content-Type	必需：指定有效负载的内容类型。接受的值为 application/json 或 charset=UTF-8。

POST 请求正文

请求 URL 是 POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.1/batches。
请求正文是名为 inputs 的 JSON 对象。
inputs 对象包含源和目标语言对的 sourceURL 与 targetURL 容器地址。使用系统分配的托管标识，使用普通存储帐户 URL（没有 SAS 或其他添加项）。格式为 https://<storage_account_name>.blob.core.chinacloudapi.cn/<container_name>。
prefix 和 suffix 字段（可选）用于筛选容器中的文档（包括文件夹）。
翻译文档时将应用 glossaries 字段（可选）的值。
每个目标语言的 targetUrl 必须唯一。

重要

如果目标中已存在同名的文件，作业将失败。在使用托管标识时，请勿在 HTTP 请求中包含 SAS 令牌 URL。如果这样做，请求将失败。

翻译容器中的所有文档

此示例请求正文引用要翻译为目标语言的所有文档的源容器。

有关详细信息，请参阅请求参数.

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

翻译容器中的特定文档

此示例请求正文引用一个要翻译为两种目标语言的源文档。

重要

除了前面提到的请求参数外，还必须包括 "storageType": "File"。否则，假定源 URL 位于容器级别。

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

使用自定义术语表翻译容器中的所有文档

此示例请求正文引用要使用词汇表翻译为目标语言的所有文档的源容器。