Managed identities for Document Translation

Important

  • Currently, Document Translation doesn't support managed identity in the global region. If you intend to use managed identities for Document Translation operations, create your Translator resource in a non-global Azure region.

  • Document Translation is only available in the S1 Standard Service Plan (Pay-as-you-go) or in the D3 Volume Discount Plan. See Cognitive Services pricing—Translator.

Managed identities for Azure resources are service principals that create an Azure Active Directory (Azure AD) identity and specific permissions for Azure managed resources:

  • You can use managed identities to grant access to any resource that supports Azure AD authentication, including your own applications. Managed identities eliminate the need for you to include shared access signature tokens (SAS) with your HTTP requests.

  • To grant access to an Azure resource, you'll assign an Azure role to a managed identity using Azure role-based access control (Azure RBAC).

  • There's no added cost to use managed identities in Azure.

Tip

  • When using managed identities, don't include a SAS token URL with your HTTP requests—your requests will fail.

  • Managed identities are a safer way to grant access to data without having SAS tokens included with your HTTP requests.

Prerequisites

To get started, you'll need:

Managed identity assignments

There are two types of managed identities: system-assigned and user-assigned. Currently, Document Translation supports system-assigned managed identity:

  • A system-assigned managed identity is enabled directly on a service instance. It isn't enabled by default; you must go to your resource and update the identity setting.

  • The system-assigned managed identity is tied to your resource throughout its lifecycle. If you delete your resource, the managed identity will be deleted as well.

In the following steps, we'll enable a system-assigned managed identity and grant your Translator resource limited access to your Azure blob storage account.

Enable a system-assigned managed identity

Important

To enable a system-assigned managed identity, you need Microsoft.Authorization/roleAssignments/write permissions, such as Owner or User Access Administrator. You can specify a scope at four levels: management group, subscription, resource group, or resource.

  1. Sign in to the Azure portal using an account associated with your Azure subscription.

  2. Navigate to your Translator resource page in the Azure portal.

  3. In the left rail, select Identity from the Resource Management list:

    Screenshot: resource management identity tab in the Azure portal.

  4. In the main window, toggle the System assigned Status tab to On.

Grant access to your storage account

You need to grant Translator access to your storage account before it can create, read, or delete blobs. Once you've enabled Translator with a system-assigned managed identity, you can use Azure role-based access control (Azure RBAC), to give Translator access to your Azure storage containers.

The Storage Blob Data Contributor role gives Translator (represented by the system-assigned managed identity) read, write, and delete access to the blob container and data.

  1. Under Permissions select Azure role assignments:

    Screenshot: enable system-assigned managed identity in Azure portal.

  2. An Azure role assignments page will open. Choose your subscription from the drop-down menu then select + Add role assignment.

    Screenshot: Azure role assignments page in the Azure portal.

    Note

    If you are unable to assign a role in the Azure portal because the Add > Add role assignment option is disabled or get the permissions error, "you do not have permissions to add role assignment at this scope", check that you are currently signed in as a user with an assigned a role that has Microsoft.Authorization/roleAssignments/write permissions such as Owner or User Access Administrator at the storage scope for the storage resource.

  3. Next, you're going to assign a Storage Blob Data Contributor role to your Translator service resource. In the Add role assignment pop-up window, complete the fields as follows and select Save:

    Field Value
    Scope Storage.
    Subscription The subscription associated with your storage resource.
    Resource The name of your storage resource.
    Role Storage Blob Data Contributor.

    Screenshot: add role assignments page in the Azure portal.

  4. After you've received the Added Role assignment confirmation message, refresh the page to see the added role assignment.

    Screenshot: Added role assignment confirmation pop-up message.

  5. If you don't see the change right away, wait and try refreshing the page once more. When you assign or remove role assignments, it can take up to 30 minutes for changes to take effect.

    Screenshot: Azure role assignments window.

HTTP requests

  • A batch Document Translation request is submitted to your Translator service endpoint via a POST request.

  • With managed identity and Azure RBAC, you'll no longer need to include SAS URLs.

  • If successful, the POST method returns a 202 Accepted response code and the batch request is created by the service.

  • The translated documents will appear in your target container.

Headers

The following headers are included with each Document Translator API request:

HTTP header Description
Ocp-Apim-Subscription-Key Required: The value is the Azure key for your Translator or Cognitive Services resource.
Content-Type Required: Specifies the content type of the payload. Accepted values are application/json or charset=UTF-8.

POST request body

  • The request URL is POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches

  • The request body is a JSON object named inputs.

  • The inputs object contains both sourceURL and targetURL container addresses for your source and target language pairs

  • The prefix and suffix fields (optional) are used to filter documents in the container including folders.

  • A value for the glossaries field (optional) is applied when the document is being translated.

  • The targetUrl for each target language must be unique.

Note

If a file with the same name already exists in the destination, the job will fail.

Translate all documents in a container

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr"
                    "language": "fr"
                }
            ]
        }
    ]
}

Translate a specific document in a container

  • Required: "storageType": "File"
  • The sample request below shows a single document getting translated into two target languages
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-es/Target-Spanish.docx"
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-de/Target-German.docx",
                    "language": "de"
                }
            ]
        }
    ]
}

Translate documents using a custom glossary

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://myblob.blob.core.windows.net/source",
                "filter": {
                    "prefix": "myfolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://myblob.blob.core.windows.net/target",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "https:// myblob.blob.core.windows.net/glossary/en-es.xlf",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Great! You've learned how to enable and use a system-assigned managed identity. With managed identity for Azure Resources and Azure RBAC, you granted Translator specific access rights to your storage resource without including SAS tokens with your HTTP requests.

Next steps

Quickstart

Tutorial