用于文档翻译的托管标识

项目
06/06/2024
可使用托管标识向支持 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 门户的 Azure 基于角色的访问控制 ( Azure RBAC ) 。
与翻译器资源位于同一区域的 Azure Blob 存储帐户。你还需要创建一个容器，用于存储和整理存储帐户中的 blob 数据。
如果存储帐户位于防火墙后面，则必须启用以下配置：
转到 Azure 门户并登录 Azure 帐户。
选择“存储帐户”。
在左窗格的“安全性 + 网络”组中，选择“网络”。
在“防火墙和虚拟网络”选项卡中，选择“从所选虚拟网络和 IP 地址启用”。
取消选中所有复选框。
确保选中“Microsoft 网络路由”。
在“ 资源实例 ”部分下，选择 Microsoft.CognitiveServices/accounts 作为资源类型，并选择翻译器资源作为实例名称。
确保选中“ 允许受信任服务列表中的 Azure 服务访问此存储帐户 ”框。有关管理例外的详细信息， 请参阅 配置 Azure 存储防火墙和虚拟网络。
选择“保存”。

网络更改最多可能需要 5 分钟才会传播。

尽管现在允许网络访问，但翻译器资源仍无法访问存储帐户中的数据。需要为翻译器资源创建托管标识并分配特定的访问角色。

托管标识分配

有两种类型的托管标识：系统分配的托管标识和用户分配的托管标识。目前，文档翻译支持系统分配的托管标识：
系统分配的托管标识直接在服务实例上启用。此标识默认不会启用，因此你必须转到资源并更新标识设置。
系统分配的托管标识在其整个生命周期内与资源绑定。如果删除资源，则托管标识也将被删除。

在以下步骤中，我们将启用系统分配的托管标识，并授予翻译器资源对 Azure Blob 存储帐户的有限访问权限。

启用系统分配的托管标识

你必须先向翻译器资源授予对存储帐户的访问权限，然后才能创建、读取或删除 blob。使用系统分配的托管标识启用了翻译器资源后，可使用 Azure 基于角色的访问控制 ( Azure RBAC ) 向翻译器提供对 Azure 存储容器的访问权限。
转到 Azure 门户并登录 Azure 帐户。
选择翻译器资源。
在左窗格的“资源管理”组中，选择“标识”。
在“ 系统分配 ”选项卡中，打开“ 状态 ”切换开关。

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

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

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

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"
使用自定义术语表翻译容器中的所有文档

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

有关详细信息， 请参阅 请求参数。
"inputs": [ "source": { "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>", "filter": { "prefix": "myfolder/" "targets": [ "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>", "language": "es", "glossaries": [ "glossaryUrl": "https://<storage_account_name>.blob.core.windows.net/<glossary_container_name>/en-es.xlf", "format": "xliff"
很好！你已了解如何启用和使用系统分配的托管标识。使用 Azure 资源托管标识和 Azure RBAC ，你授予了翻译器对存储资源的特定访问权限，而无需在 HTTP 请求中包含 SAS 令牌。

快速入门：文档翻译入门

教程：使用托管标识从 Web 应用访问 Azure 存储
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。有关详细信息，请参阅： https://aka.ms/ContentUserFeedback 。

提交和查看相关反馈

用于文档翻译的托管标识

托管标识分配

启用系统分配的托管标识

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

POST 请求正文

翻译容器中的所有文档

翻译容器中的特定文档

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