Post
Ask Question

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.
  1. Target Endpoint
    Get it from Target Form Recognizer app>Resource Management>Keys and Endpoint>Endpoint

  2. Target Subscription Key
    Get it from Target Form Recognizer app>Resource Management>Keys and Endpoint>Key or Key 2

  3. Target Resource Id
    Get it from Target Form Recognizer app>Resource Management>Properties>Resource Id

  4. Target Resource Region
    Get it from Target Form Recognizer app>Resource Management>Keys and Endpoint>Location

  5. Source Endpoint
    Get it from Source Form Recognizer app>Resource Management>Keys and Endpoint>Endpoint

  6. 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​
  1. {  
  2.     "modelList": [{  
  3.         "modelId": "00a7a4ac-abc4-23ds-234r-366cc364e2c2",  
  4.         "modelName": "GV",  
  5.         "attributes": {  
  6.             "isComposed": true  
  7.         },  
  8.         "status": "ready",  
  9.         "createdDateTime": "2020-09-27T18:38:29Z",  
  10.         "lastUpdatedDateTime": "2020-09-27T18:38:30Z"  
  11.     }, {  
  12.         "modelId": "01d3ccef-c987-4689-123f-65be2860c25e",  
  13.         "modelName": "AV",  
  14.         "attributes": {  
  15.             "isComposed": false  
  16.         },  
  17.         "status": "ready",  
  18.         "createdDateTime": "2020-11-03T17:32:54Z",  
  19.         "lastUpdatedDateTime": "2020-11-03T17:32:59Z"  
  20.     }],  
  21.     "nextLink": "https://xxxx.api.cognitive.microsoft.com/formrecognizer/v2.1-preview.1/custom/models?nextLink=2!204!MTJmYmQ0ZjJjOTFhYiY0Mi1iMjhjkxMGMvbW991OS45OTk5OTk5WiEDAwMTA4IXN1YnNjcmlwdGlvbjghOTk1c2VMYWJlbEZpbGUuanNvbiEwMDAwMOTo5OS0xMi0zMVQyMzo1nMvMTU1NTVjNWEzMTA3NGZjN2FlZWM1MGQ0YjY4MU3Mzg0NGQ2LWY3MjItNGkZWxzLzkL-"  
  22. }  
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
  1. {  
  2.     "modelId": "85f23761-1234-3423-dsef-kfrd648a65c3",  
  3.     "accessToken": "a1b3119a-fred-4312-5643-gtrk33410737",  
  4.     "expirationDateTimeTicks": 1619123456  
  5. }  
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.
  1. {  
  2.     "targetResourceId": "{Target Resource Id}",  
  3.     "targetResourceRegion": "{Target Resource Region}",  
  4.     "copyAuthorization": {  
  5.         "modelId": "85f23761-1234-3423-dsef-kfrd648a65c3",  
  6.         "accessToken": "a1b3119a-fred-4312-5643-gtrk33410737",  
  7.         "expirationDateTimeTicks": 1619123456  
  8.     }  
  9. }  
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.


Similar Articles