Skip to content

Commit 0b71f19

Browse files
denreadenrea
authored
Merge pull request #189658 from laujan/update-managed-identities-steps
update managed identities and related articles
2 parents d100d4c + 4616347 commit 0b71f19

File tree

4 files changed

+182
-37
lines changed

4 files changed

+182
-37
lines changed

‎articles/cognitive-services/Translator/document-translation/get-started-with-document-translation.md

Lines changed: 35 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -22,17 +22,39 @@ ms.custom: mode-other
2222

2323
> [!NOTE]
2424
>
25-
> 1. Generally, when you create a Cognitive Service resource in the Azure portal, you have the option to create a multi-service subscription key or a single-service subscription key. However, Document Translation is currently supported in the Translator (single-service) resource only, and is **not** included in the Cognitive Services (multi-service) resource.
26-
> 2. 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](https://azure.microsoft.com/pricing/details/cognitive-services/translator/).
25+
> * Generally, when you create a Cognitive Service resource in the Azure portal, you have the option to create a multi-service subscription key or a single-service subscription key. However, Document Translation is currently supported in the Translator (single-service) resource only, and is **not** included in the Cognitive Services (multi-service) resource.
26+
>
27+
> * Document Translation is **only** supported in the S1 Standard Service Plan (Pay-as-you-go) or in the D3 Volume Discount Plan. _See_ [Cognitive Services pricing—Translator](https://azure.microsoft.com/pricing/details/cognitive-services/translator/).
2728
>
2829
2930
To get started, you'll need:
3031

3132
* An active [**Azure account**](https://azure.microsoft.com/free/cognitive-services/). If you don't have one, you can [**create a free account**](https://azure.microsoft.com/free/).
3233

33-
* A [**single-service Translator resource**](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) (**not** a multi-service Cognitive Services resource).
34+
* An [**Azure blob storage account**](https://portal.azure.com/#create/Microsoft.StorageAccount-ARM). You'll create containers to store and organize your blob data within your storage account.
35+
36+
* A [**single-service Translator resource**](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) (**not** a multi-service Cognitive Services resource):
37+
38+
**Complete the Translator project and instance details fields as follows:**
39+
40+
1. **Subscription**. Select one of your available Azure subscriptions.
41+
42+
1. **Resource Group**. You can create a new resource group or add your resource to a pre-existing resource group that shares the same lifecycle, permissions, and policies.
43+
44+
1. **Resource Region**. Choose **Global** unless your business or application requires a specific region. If you're planning on using a [system-assigned managed identity](managed-identity.md) for authentication, choose a **non-global** region.
3445

35-
* An [**Azure blob storage account**](https://portal.azure.com/#create/Microsoft.StorageAccount-ARM). You will create containers to store and organize your blob data within your storage account.
46+
1. **Name**. Enter the name you have chosen for your resource. The name you choose must be unique within Azure.
47+
48+
> [!NOTE]
49+
> Document Translation requires a custom domain endpoint. The value that you enter in the Name field will be the custom domain name parameter for your endpoint.
50+
51+
1. **Pricing tier**. Document Translation isn't supported in the free tier. Select Standard S1 to try the service.
52+
53+
1. Select **Review + Create**.
54+
55+
1. Review the service terms and select **Create** to deploy your resource.
56+
57+
1. After your resource has successfully deployed, select **Go to resource**.
3658

3759
## Custom domain name and subscription key
3860

@@ -88,11 +110,11 @@ The `sourceUrl` , `targetUrl` , and optional `glossaryUrl` must include a Share
88110
>
89111
> * If you're translating **multiple** files (blobs) in an operation, **delegate SAS access at the container level**.
90112
> * If you're translating a **single** file (blob) in an operation, **delegate SAS access at the blob level**.
91-
>
113+
> * As an alternative to SAS tokens, you can use a [**system-assigned managed identity**](managed-identity.md) for authentication.
92114
93-
## Document Translation: HTTP requests
115+
## HTTP requests
94116

95-
A batch Document Translation request is submitted to your Translator service endpoint via a POST request. If successful, the POST method returns a `202 Accepted` response code and the batch request is created by the service.
117+
A batch Document Translation request is submitted to your Translator service endpoint via a POST request. If successful, the POST method returns a `202 Accepted` response code and the batch request is created by the service. The translated documents will be listed in your target container.
96118

97119
### HTTP headers
98120

@@ -102,7 +124,6 @@ The following headers are included with each Document Translator API request:
102124
|---|--|
103125
|Ocp-Apim-Subscription-Key|**Required**: The value is the Azure subscription key for your Translator or Cognitive Services resource.|
104126
|Content-Type|**Required**: Specifies the content type of the payload. Accepted values are application/json or charset=UTF-8.|
105-
|Content-Length|**Required**: the length of the request body.|
106127

107128
### POST request body properties
108129

@@ -139,9 +160,9 @@ The following headers are included with each Document Translator API request:
139160

140161
### Translate a specific document in a container
141162

142-
* Ensure you have specified "storageType": "File"
143-
* Ensure you have created source URL & SAS token for the specific blob/document (not for the container)
144-
* Ensure you have specified the target filename as part of the target URL – though the SAS token is still for the container.
163+
* Specify `"storageType": "File"`
164+
* If you aren't using a [**system-assigned managed identity**](managed-identity.md) for authentication, make sure you've created source URL & SAS token for the specific blob/document (not for the container)
165+
* Ensure you've specified the target filename as part of the target URL – though the SAS token is still for the container.
145166
* Sample request below shows a single document getting translated into two target languages
146167

147168
```json
@@ -1274,7 +1295,7 @@ The table below lists the limits for data that you send to Document Translation.
12741295
|Number of target languages in a batch| ≤ 10 |
12751296
|Size of Translation memory file| ≤ 10 MB|
12761297

1277-
Document Translation can not be used to translate secured documents such as those with an encrypted password or with restricted access to copy content.
1298+
Document Translation can't be used to translate secured documents such as those with an encrypted password or with restricted access to copy content.
12781299

12791300
## Troubleshooting
12801301

@@ -1284,8 +1305,8 @@ Document Translation can not be used to translate secured documents such as thos
12841305
|------------------|-------------|-----------------|
12851306
| 200 | OK | The request was successful. |
12861307
| 400 | Bad Request | A required parameter is missing, empty, or null. Or, the value passed to either a required or optional parameter is invalid. A common issue is a header that is too long. |
1287-
| 401 | Unauthorized | The request is not authorized. Check to make sure your subscription key or token is valid and in the correct region. When managing your subscription on the Azure portal, please ensure you're using the **Translator** single-service resource _not_ the **Cognitive Services** multi-service resource.
1288-
| 429 | Too Many Requests | You have exceeded the quota or rate of requests allowed for your subscription. |
1308+
| 401 | Unauthorized | The request isn't authorized. Check to make sure your subscription key or token is valid and in the correct region. When managing your subscription on the Azure portal, make sure you're using the **Translator** single-service resource _not_ the **Cognitive Services** multi-service resource.
1309+
| 429 | Too Many Requests | You've exceeded the quota or rate of requests allowed for your subscription. |
12891310
| 502 | Bad Gateway | Network or server-side issue. May also indicate invalid headers. |
12901311

12911312
## Learn more

‎articles/cognitive-services/Translator/document-translation/managed-identity.md

Lines changed: 134 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,29 +7,35 @@ manager: nitinme
77
ms.service: cognitive-services
88
ms.subservice: translator-text
99
ms.topic: how-to
10-
ms.date: 02/22/2022
10+
ms.date: 02/28/2022
1111
ms.author: lajanuar
1212
---
1313

1414
# Managed identities for Document Translation
1515

1616
> [!IMPORTANT]
1717
>
18-
> Managed identities for Azure resources are currently unavailable for Document Translation service in the global region. If you intend to use managed identities for Document Translation operations, [create your Translator resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) in a non-global Azure region.
18+
> * 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](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) in a non-global Azure region.
19+
>
20+
> * 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](https://azure.microsoft.com/pricing/details/cognitive-services/translator/).
21+
>
1922
2023
Managed identities for Azure resources are service principals that create an Azure Active Directory (Azure AD) identity and specific permissions for Azure managed resources:
2124

22-
* You can use managed identities to grant access to any resource that supports Azure AD authentication, including your own applications. Unlike security keys and authentication tokens, managed identities eliminate the need for developers to manage credentials.
25+
* 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.
2326

24-
* To grant access to an Azure resource, assign an Azure role to a managed identity using [Azure role-based access control (Azure RBAC)](../../../role-based-access-control/overview.md).
27+
* 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)](../../../role-based-access-control/overview.md).
2528

2629
* There's no added cost to use managed identities in Azure.
2730

2831
> [!TIP]
29-
> Managed identities eliminate the need for you to manage credentials, including Shared Access Signature (SAS) tokens. Managed identities are a safer way to grant access to data without having credentials in your code.
32+
>
33+
> * When using managed identities, don't include a SAS token URL with your HTTP requests—your requests will fail.
34+
>
35+
> * Managed identities are a safer way to grant access to data without having SAS tokens included with your HTTP requests.
3036
31-
## Prerequisites
3237

38+
## Prerequisites
3339
To get started, you'll need:
3440

3541
* An active [**Azure account**](https://azure.microsoft.com/free/cognitive-services/)—if you don't have one, you can [**create a free account**](https://azure.microsoft.com/free/).
@@ -38,7 +44,7 @@ To get started, you'll need:
3844

3945
* A brief understanding of [**Azure role-based access control (Azure RBAC)**](../../../role-based-access-control/role-assignments-portal.md) using the Azure portal.
4046

41-
* An [**Azure blob storage account**](https://portal.azure.com/#create/Microsoft.StorageAccount-ARM) in the same region as your Translator resource. You'll create containers to store and organize your blob data within your storage account.
47+
* An [**Azure blob storage account**](https://portal.azure.com/#create/Microsoft.StorageAccount-ARM) in the same region as your Translator resource. You'll create containers to store and organize your blob data within your storage account.
4248

4349
* **If your storage account is behind a firewall, you must enable the following configuration**: </br>
4450

@@ -54,9 +60,9 @@ To get started, you'll need:
5460

5561
## Managed identity assignments
5662

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

59-
* 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.
65+
* 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.
6066

6167
* 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.
6268

@@ -80,7 +86,7 @@ In the following steps, we'll enable a system-assigned managed identity and gran
8086

8187
## Grant access to your storage account
8288

83-
You need to grant Translator access to your storage account before it can create, read, or delete blobs. Now that you enabled Translator with a system-assigned managed identity, you can use Azure role-based access control (Azure RBAC), to give Translator access to Azure storage.
89+
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.
8490

8591
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.
8692

@@ -115,9 +121,126 @@ The **Storage Blob Data Contributor** role gives Translator (represented by the
115121

116122
:::image type="content" source="../media/managed-identities/assigned-roles-window.png" alt-text="Screenshot: Azure role assignments window.":::
117123

118-
Great! You've completed the steps to enable a system-assigned managed identity. With managed identity and Azure RBAC, you granted Translator specific access rights to your storage resource without having to manage credentials such as SAS tokens.
124+
## HTTP requests
125+
126+
* A batch Document Translation request is submitted to your Translator service endpoint via a POST request.
127+
128+
* With managed identity and Azure RBAC, you'll no longer need to include SAS URLs.
129+
130+
* If successful, the POST method returns a `202 Accepted` response code and the batch request is created by the service.
131+
132+
* The translated documents will appear in your target container.
133+
134+
### Headers
135+
136+
The following headers are included with each Document Translator API request:
137+
138+
|HTTP header|Description|
139+
|---|--|
140+
|Ocp-Apim-Subscription-Key|**Required**: The value is the Azure subscription key for your Translator or Cognitive Services resource.|
141+
|Content-Type|**Required**: Specifies the content type of the payload. Accepted values are application/json or charset=UTF-8.|
142+
143+
### POST request body
144+
145+
* The request URL is POST `https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches`
146+
147+
* The request body is a JSON object named `inputs`.
148+
* The `inputs` object contains both `sourceURL` and `targetURL` container addresses for your source and target language pairs
149+
* The `prefix` and `suffix` fields (optional) are used to filter documents in the container including folders.
150+
* A value for the `glossaries` field (optional) is applied when the document is being translated.
151+
* The `targetUrl` for each target language must be unique.
152+
153+
>[!NOTE]
154+
> If a file with the same name already exists in the destination, the job will fail.
155+
156+
<!-- markdownlint-disable MD024 -->
157+
### Translate all documents in a container
158+
159+
```json
160+
{
161+
"inputs": [
162+
{
163+
"source": {
164+
"sourceUrl": "https://my.blob.core.windows.net/source-en"
165+
},
166+
"targets": [
167+
{
168+
"targetUrl": "https://my.blob.core.windows.net/target-fr"
169+
"language": "fr"
170+
}
171+
]
172+
}
173+
]
174+
}
175+
```
176+
177+
### Translate a specific document in a container
178+
179+
* **Required**: "storageType": "File"
180+
* The sample request below shows a single document getting translated into two target languages
181+
182+
```json
183+
{
184+
"inputs": [
185+
{
186+
"storageType": "File",
187+
"source": {
188+
"sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx"
189+
},
190+
"targets": [
191+
{
192+
"targetUrl": "https://my.blob.core.windows.net/target-es/Target-Spanish.docx"
193+
"language": "es"
194+
},
195+
{
196+
"targetUrl": "https://my.blob.core.windows.net/target-de/Target-German.docx",
197+
"language": "de"
198+
}
199+
]
200+
}
201+
]
202+
}
203+
```
204+
205+
### Translate documents using a custom glossary
206+
207+
```json
208+
{
209+
"inputs": [
210+
{
211+
"source": {
212+
"sourceUrl": "https://myblob.blob.core.windows.net/source",
213+
"filter": {
214+
"prefix": "myfolder/"
215+
}
216+
},
217+
"targets": [
218+
{
219+
"targetUrl": "https://myblob.blob.core.windows.net/target",
220+
"language": "es",
221+
"glossaries": [
222+
{
223+
"glossaryUrl": "https:// myblob.blob.core.windows.net/glossary/en-es.xlf",
224+
"format": "xliff"
225+
}
226+
]
227+
}
228+
]
229+
}
230+
]
231+
}
232+
```
233+
234+
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.
119235

120236
## Next steps
121237

238+
**Quickstart**
239+
240+
> [!div class="nextstepaction"]
241+
> [Get started with Document Translation](get-started-with-document-translation.md)
242+
243+
**Tutorial**
244+
122245
> [!div class="nextstepaction"]
123246
> [Access Azure Storage from a web app using managed identities](/azure/app-service/scenario-secure-app-access-storage?toc=/azure/cognitive-services/translator/toc.json&bc=/azure/cognitive-services/translator/breadcrumb/toc.json)

‎articles/cognitive-services/Translator/toc.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -110,11 +110,11 @@ items:
110110
items:
111111
- name: Generate SAS tokens for Document Translation
112112
href: document-translation/create-sas-tokens.md
113-
- name: Create and use managed identity
113+
- name: Create and use managed identities
114114
href: document-translation/managed-identity.md
115115
- name: Reference
116116
items:
117-
- name: Document Translation REST APIs
117+
- name: Document Translation REST APIs
118118
href: document-translation/reference/rest-api-guide.md
119119
- name: Get supported document formats
120120
href: document-translation/reference/get-supported-document-formats.md

0 commit comments

Comments
 (0)