Skip to content

Commit 758ed1d

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #260880 from laujan/190653-remaining-formrecognizer-references
update copy model
2 parents 6f6f1d2 + ee28b94 commit 758ed1d

File tree

3 files changed

+189
-9
lines changed

3 files changed

+189
-9
lines changed

‎articles/ai-services/document-intelligence/disaster-recovery.md

Lines changed: 173 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -50,22 +50,189 @@ If your app or business depends on the use of a Document Intelligence custom mod
5050

5151
::: moniker-end
5252

53-
::: moniker range=">=doc-intel-3.0.0"
53+
::: moniker range="doc-intel-4.0.0"
54+
55+
## Copy API overview
56+
57+
The process for copying a custom model consists of the following steps:
58+
59+
1. First you issue a copy authorization request to the target resource—that is, the resource that receives the copied model. You receive back the URL of the newly created target model that receives the copied model.
60+
1. Next you send the copy request to the source resource—the resource that contains the model to be copied with the payload (copy authorization) returned from the previous call. You receive back a URL that you can query to track the progress of the operation.
61+
1. You use your source resource credentials to query the progress URL until the operation is a success. You can also query the new model ID in the target resource to get the status of the new model
62+
63+
## Generate Copy authorization request
64+
65+
The following HTTP request gets copy authorization from your target resource. You need to enter the endpoint and key of your target resource as headers.
66+
67+
```http
68+
POST https://<your-resource-name>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2023-10-31-preview
69+
Ocp-Apim-Subscription-Key: {<your-key>}
70+
```
71+
72+
Request body
73+
74+
```json
75+
{
76+
"modelId": "target-model-name",
77+
"description": "Copied from SCUS"
78+
}
79+
```
80+
81+
You receive a `200` response code with response body that contains the JSON payload required to initiate the copy.
82+
83+
```json
84+
{
85+
"targetResourceId": "/subscriptions/{targetSub}/resourceGroups/{targetRG}/providers/Microsoft.CognitiveServices/accounts/{targetService}",
86+
"targetResourceRegion": "region",
87+
"targetModelId": "target-model-name",
88+
"targetModelLocation": "model path",
89+
"accessToken": "access token",
90+
"expirationDateTime": "timestamp"
91+
}
92+
```
93+
94+
## Start Copy operation
95+
96+
The following HTTP request starts the copy operation on the source resource. You need to enter the endpoint and key of your source resource as the url and header. Notice that the request URL contains the model ID of the source model you want to copy.
97+
98+
```http
99+
POST https://<your-resource-name>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2023-10-31-preview
100+
Ocp-Apim-Subscription-Key: {<your-key>}
101+
```
102+
103+
The body of your request is the response from the previous step.
104+
105+
```json
106+
{
107+
"targetResourceId": "/subscriptions/{targetSub}/resourceGroups/{targetRG}/providers/Microsoft.CognitiveServices/accounts/{targetService}",
108+
"targetResourceRegion": "region",
109+
"targetModelId": "target-model-name",
110+
"targetModelLocation": "model path",
111+
"accessToken": "access token",
112+
"expirationDateTime": "timestamp"
113+
}
114+
```
115+
116+
You receive a `202\Accepted` response with an Operation-Location header. This value is the URL that you use to track the progress of the operation. Copy it to a temporary location for the next step.
117+
118+
```http
119+
HTTP/1.1 202 Accepted
120+
Operation-Location: https://<your-resource-name>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2023-10-31-preview
121+
```
122+
123+
> [!NOTE]
124+
> The Copy API transparently supports the [AEK/CMK](https://msazure.visualstudio.com/Cognitive%20Services/_wiki/wikis/Cognitive%20Services.wiki/52146/Customer-Managed-Keys) feature. This doesn't require any special treatment, but note that if you're copying between an unencrypted resource to an encrypted resource, you need to include the request header `x-ms-forms-copy-degrade: true`. If this header is not included, the copy operation will fail and return a `DataProtectionTransformServiceError`.
125+
126+
## Track Copy progress
127+
128+
```console
129+
GET https://<your-resource-name>.cognitiveservices.azure.com/documentintelligence/operations/{<operation-id>}?api-version=2023-10-31-preview
130+
Ocp-Apim-Subscription-Key: {<your-key>}
131+
```
132+
133+
### Track the target model ID
134+
135+
You can also use the **[Get model](/rest/api/aiservices/document-models/get-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)** API to track the status of the operation by querying the target model. Call the API using the target model ID that you copied down from the [Generate Copy authorization request](#generate-copy-authorization-request) response.
136+
137+
```http
138+
GET https://<your-resource-name>/documentintelligence/documentModels/{modelId}?api-version=2023-10-31-preview" -H "Ocp-Apim-Subscription-Key: <your-key>
139+
```
140+
141+
In the response body, you see information about the model. Check the `"status"` field for the status of the model.
142+
143+
```http
144+
HTTP/1.1 200 OK
145+
Content-Type: application/json; charset=utf-8
146+
{"modelInfo":{"modelId":"33f4d42c-cd2f-4e74-b990-a1aeafab5a5d","status":"ready","createdDateTime":"2020-02-26T16:59:28Z","lastUpdatedDateTime":"2020-02-26T16:59:34Z"},"trainResult":{"trainingDocuments":[{"documentName":"0.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"1.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"2.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"3.pdf","pages":1,"errors":[],"status":"succeeded"},{"documentName":"4.pdf","pages":1,"errors":[],"status":"succeeded"}],"errors":[]}}
147+
```
148+
149+
## cURL sample code
150+
151+
The following code snippets use cURL to make API calls. You also need to fill in the model IDs and subscription information specific to your own resources.
152+
153+
### Generate Copy authorization
154+
155+
**Request**
156+
157+
```bash
158+
curl -i -X POST "<your-resource-name>/documentintelligence/documentModels:authorizeCopy?api-version=2023-10-31-preview"
159+
-H "Content-Type: application/json"
160+
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
161+
--data-ascii "{
162+
'modelId': '{modelId}',
163+
'description': '{description}'
164+
}"
165+
```
166+
167+
**Successful response**
168+
169+
```json
170+
{
171+
"targetResourceId": "string",
172+
"targetResourceRegion": "string",
173+
"targetModelId": "string",
174+
"targetModelLocation": "string",
175+
"accessToken": "string",
176+
"expirationDateTime": "string"
177+
}
178+
```
179+
180+
### Begin Copy operation
181+
182+
**Request**
183+
184+
```bash
185+
curl -i -X POST "<your-resource-name>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2023-10-31-preview"
186+
-H "Content-Type: application/json"
187+
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
188+
--data-ascii "{
189+
'targetResourceId': '{targetResourceId}',
190+
'targetResourceRegion': {targetResourceRegion}',
191+
'targetModelId': '{targetModelId}',
192+
'targetModelLocation': '{targetModelLocation}',
193+
'accessToken': '{accessToken}',
194+
'expirationDateTime': '{expirationDateTime}'
195+
}"
196+
197+
```
198+
199+
**Successful response**
200+
201+
```http
202+
HTTP/1.1 202 Accepted
203+
Operation-Location: https://<your-resource-name>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2023-10-31-preview
204+
```
205+
206+
### Track copy operation progress
207+
208+
You can use the [**Get operation**](/rest/api/aiservices/miscellaneous/get-operation?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) API to list all document model operations (succeeded, in-progress, or failed) associated with your Document Intelligence resource. Operation information only persists for 24 hours. Here's a list of the operations (operationId) that can be returned:
209+
210+
* documentModelBuild
211+
* documentModelCompose
212+
* documentModelCopyTo
213+
214+
### Track the target model ID
215+
216+
If the operation was successful, the document model can be accessed using the [**getModel**](/rest/api/aiservices/document-models/get-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP) (get a single model), or [**GetModels**](/rest/api/aiservices/document-models/get-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTPs) (get a list of models) APIs.
217+
218+
::: moniker-end
219+
220+
::: moniker range="doc-intel-3.0.0 || doc-intel-3.1.0"
54221

55222
## Copy API overview
56223

57224
The process for copying a custom model consists of the following steps:
58225

59226
1. First you issue a copy authorization request to the target resource&mdash;that is, the resource that receives the copied model. You receive back the URL of the newly created target model that receives the copied model.
60227
1. Next you send the copy request to the source resource&mdash;the resource that contains the model to be copied with the payload (copy authorization) returned from the previous call. You receive back a URL that you can query to track the progress of the operation.
61-
1. You use your source resource credentials to query the progress URL until the operation is a success. With v3.0, you can also query the new model ID in the target resource to get the status of the new model.
228+
1. You use your source resource credentials to query the progress URL until the operation is a success. You can also query the new model ID in the target resource to get the status of the new model
62229

63230
## Generate Copy authorization request
64231

65232
The following HTTP request gets copy authorization from your target resource. You need to enter the endpoint and key of your target resource as headers.
66233

67234
```http
68-
POST https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/documentModels:authorizeCopy?api-version=2023-07-31
235+
POST https://{TARGET_FORM_RECOGNIZER_RESOURCE_ENDPOINT}/formrecognizer/documentModels:authorizeCopy?api-version=2023-10-31-preview
69236
Ocp-Apim-Subscription-Key: {TARGET_FORM_RECOGNIZER_RESOURCE_KEY}
70237
```
71238

@@ -135,7 +302,7 @@ Ocp-Apim-Subscription-Key: {SOURCE_FORM_RECOGNIZER_RESOURCE_KEY}
135302
You can also use the **[Get model](/rest/api/aiservices/document-models/get-model?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)** API to track the status of the operation by querying the target model. Call the API using the target model ID that you copied down from the [Generate Copy authorization request](#generate-copy-authorization-request) response.
136303

137304
```http
138-
GET https://{YOUR-ENDPOINT}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31" -H "Ocp-Apim-Subscription-Key: {YOUR-KEY}
305+
GET https://{YOUR-ENDPOINT}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31" -H "Ocp-Apim-Subscription-Key: <YOUR-KEY>
139306
```
140307

141308
In the response body, you see information about the model. Check the `"status"` field for the status of the model.
@@ -157,7 +324,7 @@ The following code snippets use cURL to make API calls. You also need to fill in
157324
```bash
158325
curl -i -X POST "{YOUR-ENDPOINT}formrecognizer/documentModels:authorizeCopy?api-version=2023-07-31"
159326
-H "Content-Type: application/json"
160-
-H "Ocp-Apim-Subscription-Key: {YOUR-KEY}"
327+
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
161328
--data-ascii "{
162329
'modelId': '{modelId}',
163330
'description': '{description}'
@@ -184,7 +351,7 @@ curl -i -X POST "{YOUR-ENDPOINT}formrecognizer/documentModels:authorizeCopy?api-
184351
```bash
185352
curl -i -X POST "{YOUR-ENDPOINT}/formrecognizer/documentModels/{modelId}:copyTo?api-version=2023-07-31"
186353
-H "Content-Type: application/json"
187-
-H "Ocp-Apim-Subscription-Key: {YOUR-KEY}"
354+
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
188355
--data-ascii "{
189356
'targetResourceId': '{targetResourceId}',
190357
'targetResourceRegion': {targetResourceRegion}',

‎articles/ai-services/document-intelligence/includes/preview-notice.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,8 @@ ms.date: 11/21/2023
1616
> * Document Intelligence public preview releases provide early access to features that are in active development.
1717
> * Features, approaches, and processes may change, prior to General Availability (GA), based on user feedback.
1818
> * The public preview version of Document Intelligence client libraries default to REST API version [**2023-10-31-preview**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP).
19+
> * Public preview version [**2023-10-31-preview**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP) is currently only available in the following Azure regions:
20+
>
21+
> * **East US**
22+
> * **West US2**
23+
> * **West Europe**

‎articles/ai-services/document-intelligence/whats-new.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,19 @@ ms.custom:
2424

2525
Document Intelligence service is updated on an ongoing basis. Bookmark this page to stay up to date with release notes, feature enhancements, and our newest documentation.
2626

27+
## December 2023
28+
29+
The [Document Intelligence SDKs](sdk-overview-v4-0.md) targeting REST API **2023-10-31-preview** are now available for use!
30+
2731
## November 2023
2832

29-
Document Intelligence **2023-10-31-preview**
33+
The Document Intelligence [**2023-10-31-preview**](https://westus.dev.cognitive.microsoft.com/docs/services?pattern=intelligence) REST API is now available. This preview API introduces new and updated capabilities:
34+
35+
* Public preview version [**2023-10-31-preview**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-10-31-preview&preserve-view=true&tabs=HTTP) is currently only available in the following Azure regions:
3036

31-
The Document Intelligence [**2023-10-31-preview**](https://westus.dev.cognitive.microsoft.com/docs/services?pattern=intelligence) REST API is now available for use! This preview API introduces new and updated capabilities:
37+
* **East US**
38+
* **West US2**
39+
* **West Europe**
3240

3341
* [Read model](concept-contract.md)
3442
* Language Expansion for Handwriting: Russian(`ru`), Arabic(`ar`), Thai(`th`).
@@ -99,7 +107,7 @@ The v3.1 API introduces new and updated capabilities:
99107
* Document Intelligence now supports more sophisticated analysis capabilities and the Studio allows one entry point (Analyze options button) for configuring the add-on capabilities with ease.
100108
* Depending on the document extraction scenario, configure the analysis range, document page range, optional detection, and premium detection features.
101109

102-
:::image type="content" source="media/studio/analyze-options.gif" alt-text="Animated screenshot showing use of the analyze options button to configure options in Studio.":::
110+
:::image type="content" source="media/studio/analyze-options.gif" alt-text="Animated screenshot showing use of the analyze-options button to configure options in Studio.":::
103111

104112
> [!NOTE]
105113
> Font extraction is not visualized in Document Intelligence Studio. However, you can check the styles section of the JSON output for the font detection results.

0 commit comments

Comments
 (0)