Copy/Migrate Azure Form Recognizer Custom Model To Other Subscription/Tenant

Introduction

This article guides you through the steps on how we could copy or migrate a Azure Cognitive Service Form Recognizer Custom Trained Model from one subscription or tenant to other. We can attain the above using three API calls thus can be done programmatically using script.

Before going to the API's let us define what are the things we need as pre requisites. Source is the Form Recognizer app which currently holds the model. Destination is the Form Recognizer app which we want the model to be copied/migrated to. If you have not created the destination app create it and before going to the next steps.

Target Endpoint
Get it from Target Form Recognizer app>Resource Management>Keys and Endpoint>Endpoint
Target Subscription Key
Get it from Target Form Recognizer app>Resource Management>Keys and Endpoint>Key or Key 2
Target Resource Id
Get it from Target Form Recognizer app>Resource Management>Properties>Resource Id
Target Resource Region
Get it from Target Form Recognizer app>Resource Management>Keys and Endpoint>Location
Source Endpoint
Get it from Source Form Recognizer app>Resource Management>Keys and Endpoint>Endpoint
Source Subscription Key
Get it from Source Form Recognizer app>Resource Management>Keys and Endpoint>Key or Key 2

We could break down the whole process into four steps for easiness based on four API's used.

Step 0 - Get current Model Id of custom model

This step is named step zero as we can skip this step if we already know the model id. We can get the model id using an API call (HTTP GET request).

Request URL

https://{Source Endpoint}/formrecognizer/v2.1-preview.1/custom/models?op=full

Header

Ocp-Apim-Subscription-Key : {Source Subscription Key}

By doing the above API call we will get a JSON result with the list of all custom models in the Source Form Recognizer app. Find the model id you need by the model name you have given during training phase of custom model.

A sample of the result is given below,

x-envoy-upstream-service-time: 364
apim-request-id: 77cbd3cc-a2bc-4132-b456-1501e8e621e1
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
Date: Fri, 23 Apr 2021 09:53:50 GMT
Content-Length: 5967
Content-Type: application/json; charset=utf-8

{
"modelList": [{
"modelId": "00a7a4ac-abc4-23ds-234r-366cc364e2c2",
"modelName": "GV",
"attributes": {
"isComposed": true
},
"status": "ready",
"createdDateTime": "2020-09-27T18:38:29Z",
"lastUpdatedDateTime": "2020-09-27T18:38:30Z"
}, {
"modelId": "01d3ccef-c987-4689-123f-65be2860c25e",
"modelName": "AV",
"attributes": {
"isComposed": false
},
"status": "ready",
"createdDateTime": "2020-11-03T17:32:54Z",
"lastUpdatedDateTime": "2020-11-03T17:32:59Z"
}],
"nextLink": "https://xxxx.api.cognitive.microsoft.com/formrecognizer/v2.1-preview.1/custom/models?nextLink=2!204!MTJmYmQ0ZjJjOTFhYiY0Mi1iMjhjkxMGMvbW991OS45OTk5OTk5WiEDAwMTA4IXN1YnNjcmlwdGlvbjghOTk1c2VMYWJlbEZpbGUuanNvbiEwMDAwMOTo5OS0xMi0zMVQyMzo1nMvMTU1NTVjNWEzMTA3NGZjN2FlZWM1MGQ0YjY4MU3Mzg0NGQ2LWY3MjItNGkZWxzLzkL-"
}

Now we have our seventh pre requisite ie; Model Id.

Step 1 - Generate Copy Authorization

We need to get the copy authorization from target Form Recognizer app which we will be a JSON string with new modelId , accessToken and expirationDateTimeTicks. To generate this we will be doing an API call (HTTP POST Request).

Request URL

https://{Target Endpoint}/formrecognizer/v2.1-preview.1/custom/models/copyAuthorization

Header

Ocp-Apim-Subscription-Key : {Target Subscription Key}

By doing the above API call we will get a JSON result with new modelId , accessToken and expirationDateTimeTicks.

A sample of the result is given below,

x-envoy-upstream-service-time: 32
apim-request-id: a1b3119a-fred-4312-5643-gtrk33410737
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
Date: Fri, 23 Apr 2021 09:50:51 GMT
Location: https://xxxx.api.cognitive.microsoft.com/formrecognizer/v2.1-preview.1/custom/models/85f23761-1234-3423-dsef-kfrd648a65c3
Content-Length: 140
Content-Type: application/json; charset=utf-8

{
"modelId": "85f23761-1234-3423-dsef-kfrd648a65c3",
"accessToken": "a1b3119a-fred-4312-5643-gtrk33410737",
"expirationDateTimeTicks": 1619123456
}

Copy the value between the curly braces to paste on POST Request body we do in next step.

Step 2 - Copy Model

We now have copy authorization and required details with us to do the process of copying model. We could do it with an API call(HTTP POST Request).

Request URL

https://{Source Endpoint}/formrecognizer/v2.1-preview.1/custom/models/{Model Id}/copy

Header

Content-Type: application/json
Ocp-Apim-Subscription-Key : {Source Subscription Key}

Request Body: Copy the values between curly braces from result of step 1 and paste the value as value of copyAuthorization in the below request.

{
"targetResourceId": "{Target Resource Id}",
"targetResourceRegion": "{Target Resource Region}",
"copyAuthorization": {
"modelId": "85f23761-1234-3423-dsef-kfrd648a65c3",
"accessToken": "a1b3119a-fred-4312-5643-gtrk33410737",
"expirationDateTimeTicks": 1619123456
}
}

By doing the above API call we will get a response with 202 status which indicates request is accepted. You could repeat the step 0 with target credentials to know the new Model Id and status of copying. You can stop here if your aim only was to copy the model.

Step 3 - Delete Model

This step is not mandatory, You should do it only if you need to delete the model from Source.

We could delete the custom model from Source Form Recognizer app using Source credentials by a API Call (HTTP DELETE Request).

Request URL

https://{Source Endpoint}/formrecognizer/v2.1-preview.1/custom/models/{Model Id}

Header

Ocp-Apim-Subscription-Key : {Source Subscription Key}

A response with status code 204 says the operation was successful and the operation will atke around 48 hours to complete action.

Conclusion

The operation of copy a custom model from one subscription / tenant would be successful by following the procedures above. You could find official documentation of the above API's by clicking here. There are also two more API's Get Custom Model and Get Copy Model Result which will help you better.