Pemulihan dari bencana

Konten ini berlaku untuk:v4.0 (pratinjau) | Versi sebelumnya:v3.1 (GA)v3.0 (GA)v2.1 (GA)

Saat Anda membuat sumber daya Kecerdasan Dokumen di portal Azure, Anda menentukan wilayah. Sejak saat itu, sumber daya Anda dan semua operasinya tetap terkait dengan wilayah server Azure tertentu. Jarang terjadi, tetapi bukan tidak mungkin, mengalami masalah jaringan yang melanda seluruh wilayah. Jika solusi Anda harus selalu tersedia, Anda harus mendesainnya untuk melakukan failover ke wilayah lain atau membagi beban kerja antara dua wilayah atau lebih. Kedua pendekatan memerlukan setidaknya dua sumber daya Kecerdasan Dokumen di wilayah yang berbeda dan kemampuan untuk menyinkronkan model kustom di seluruh wilayah.

COPY API memungkinkan skenario ini dengan memungkinkan Anda menyalin model kustom dari satu akun Kecerdasan Dokumen atau ke akun Lainnya, yang dapat ada di wilayah geografis yang didukung. Panduan ini menunjukkan cara menggunakan Copy REST API dengan cURL. Anda juga dapat menggunakan layanan permintaan HTTP untuk mengeluarkan permintaan.

Skenario bisnis

Jika aplikasi atau bisnis Anda bergantung pada penggunaan model kustom Kecerdasan Dokumen, sebaiknya salin model Anda ke akun Kecerdasan Dokumen lain di wilayah lain. Jika terjadi pemadaman wilayah, Anda dapat mengakses model Anda di wilayah tempat model disalin.

Prasyarat

1. Dua sumber daya Azure Kecerdasan Dokumen di wilayah Azure yang berbeda. Jika Anda tidak memilikinya, buka portal Azure dan buat sumber daya Kecerdasan Dokumen baru.
2. Kunci, URL titik akhir, dan ID langganan untuk sumber daya Kecerdasan Dokumen Anda. Anda dapat menemukan nilai ini pada tab Gambaran umum sumber daya di portal Azure.

Ringkasan API Salin

Proses untuk menyalin model kustom terdiri dari langkah-langkah berikut:

1. Pertama, Anda mengeluarkan permintaan otorisasi salin ke sumber daya target—yaitu, sumber daya yang menerima model yang disalin. Anda menerima kembali URL model target yang baru dibuat yang menerima model yang disalin.
2. Selanjutnya Anda mengirim permintaan penyalinan ke sumber daya sumber—sumber daya yang berisi model yang akan disalin dengan payload (otorisasi penyalinan) yang dikembalikan dari panggilan sebelumnya. Anda menerima kembali URL yang bisa Anda kueri untuk melacak kemajuan operasi.
3. Anda menggunakan kredensial sumber daya sumber untuk mengkueri URL kemajuan hingga operasi berhasil. Anda juga dapat mengkueri ID model baru di sumber daya target untuk mendapatkan status model baru.

Membuat permintaan otorisasi Salin

Permintaan HTTP berikut ini mendapatkan otorisasi salinan dari sumber daya target Anda. Anda perlu memasukkan titik akhir dan kunci sumber daya target Anda sebagai header.

POST https://<your-resource-endpoint>/documentintelligence/documentModels:authorizeCopy?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-key>}

Isi permintaan

{
  "modelId": "target-model-name",
  "description": "Copied from SCUS"
}

Anda menerima 200 kode respons dengan isi respons yang berisi payload JSON yang diperlukan untuk memulai salinan.

{
  "targetResourceId": "/subscriptions/{targetSub}/resourceGroups/{targetRG}/providers/Microsoft.CognitiveServices/accounts/{targetService}",
  "targetResourceRegion": "region",
  "targetModelId": "target-model-name",
  "targetModelLocation": "model path",
  "accessToken": "access token",
  "expirationDateTime": "timestamp"
}

Mulai operasi Salin

Permintaan HTTP berikut memulai operasi penyalinan pada sumber daya sumber. Anda perlu memasukkan titik akhir dan kunci sumber daya sumber Anda sebagai url dan header. Perhatikan bahwa URL permintaan berisi ID model dari model sumber yang ingin Anda salin.

POST https://<your-resource-endpoint>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-key>}

Isi permintaan Anda adalah respons dari langkah sebelumnya.

{
  "targetResourceId": "/subscriptions/{targetSub}/resourceGroups/{targetRG}/providers/Microsoft.CognitiveServices/accounts/{targetService}",
  "targetResourceRegion": "region",
  "targetModelId": "target-model-name",
  "targetModelLocation": "model path",
  "accessToken": "access token",
  "expirationDateTime": "timestamp"
}

Anda menerima 202\Accepted respons dengan header Lokasi Operasi. Nilai ini adalah URL yang Anda gunakan untuk melacak kemajuan operasi. Salin ke lokasi sementara untuk langkah selanjutnya.

HTTP/1.1 202 Accepted
Operation-Location: https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2024-02-29-preview

Catatan

API Salin secara transparan mendukung fitur AEK/CMK. Ini tidak memerlukan perlakuan khusus, tetapi perhatikan bahwa jika Anda menyalin antara sumber daya yang tidak terenkripsi ke sumber daya terenkripsi, Anda harus menyertakan header permintaan x-ms-forms-copy-degrade: true. Jika tajuk ini tidak disertakan, operasi salin akan gagal dan mengembalikan DataProtectionTransformServiceError.

Melacak kemajuan Salin

GET https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{<operation-id>}?api-version=2024-02-29-preview
Ocp-Apim-Subscription-Key: {<your-key>}

Melacak ID model target

Anda juga dapat menggunakan Get model API untuk melacak status operasi dengan mengkueri model target. Panggil API menggunakan ID model target yang Anda salin dari respons permintaan otorisasi Buat Salin.

GET https://<your-resource-endpoint>/documentintelligence/documentModels/{modelId}?api-version=2024-02-29-preview" -H "Ocp-Apim-Subscription-Key: <your-key>

Di isi respons, Anda akan melihat informasi tentang model. Periksa bidang "status" untuk status model.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"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":[]}}

kode sampel cURL

Cuplikan kode berikut menggunakan cURL untuk melakukan panggilan API. Anda juga perlu mengisi ID model dan informasi langganan khusus untuk sumber daya Anda sendiri.

Hasilkan otorisasi Salin

Permintaan

curl -i -X POST "<your-resource-endpoint>/documentintelligence/documentModels:authorizeCopy?api-version=2024-02-29-preview"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
--data-ascii "{
  'modelId': '{modelId}',
  'description': '{description}'
}"

Respons berhasil

{
  "targetResourceId": "string",
  "targetResourceRegion": "string",
  "targetModelId": "string",
  "targetModelLocation": "string",
  "accessToken": "string",
  "expirationDateTime": "string"
}

Mulai operasi Salin

Permintaan

curl -i -X POST "<your-resource-endpoint>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2024-02-29-preview"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: <YOUR-KEY>"
--data-ascii "{
  'targetResourceId': '{targetResourceId}',
  'targetResourceRegion': {targetResourceRegion}',
  'targetModelId': '{targetModelId}',
  'targetModelLocation': '{targetModelLocation}',
  'accessToken': '{accessToken}',
  'expirationDateTime': '{expirationDateTime}'
}"

Respons berhasil

HTTP/1.1 202 Accepted
Operation-Location: https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2024-02-29-preview

Lacak kemajuan operasi salin

Anda dapat menggunakan GET operation API untuk mencantumkan semua operasi model dokumen (berhasil, sedang berlangsung, atau gagal) yang terkait dengan sumber daya Kecerdasan Dokumen Anda. Informasi operasi hanya bertahan selama 24 jam. Berikut adalah daftar operasi (operationId) yang dapat dikembalikan:

• documentModelBuild
• documentModelCompose
• documentModelCopyTo

Melacak ID model target

Jika operasi berhasil, model dokumen dapat diakses menggunakan GETModel (mendapatkan satu model), atau GETModels (mendapatkan daftar model) API.

Pesan kode kesalahan umum

Kesalahan	Resolusi
400 / Permintaan Buruk dengan "code:" "1002"	Menunjukkan kesalahan validasi atau permintaan penyalinan yang dibuat dengan buruk. Masalah umum meliputi: a) Payload copyAuthorization yang tidak valid atau dimodifikasi. b) Nilai kedaluwarsa untuk expirationDateTimeTicks token (copyAuthorization payload berlaku selama 24 jam). c) Tidak valid atau tidak didukung targetResourceRegion. d) Untai targetResourceId tidak valid atau salah format.
Kegagalan otorisasi karena klaim otorisasi yang hilang atau tidak valid.	Terjadi ketika copyAuthorization payload atau konten dimodifikasi dari copyAuthorization API. Pastikan bahwa muatannya sama persis dengan konten yang dikembalikan dari panggilan copyAuthorization sebelumnya.
Tidak dapat mengambil metadata otorisasi.	Menunjukkan bahwa payload copyAuthorization sedang digunakan kembali dengan permintaan penyalinan. Permintaan salin yang berhasil tidak mengizinkan permintaan lebih lanjut yang menggunakan payload yang sama copyAuthorization . Jika Anda memunculkan kesalahan terpisah dan kemudian mencoba kembali salinan dengan payload otorisasi yang sama, kesalahan ini akan muncul. Resolusinya adalah menghasilkan muatan copyAuthorization baru lalu menerbitkan kembali permintaan penyalinan.
Permintaan transfer data tidak diizinkan karena diturunkan ke skema perlindungan data yang kurang aman.	Terjadi saat menyalin antara sumber daya AEK yang diaktifkan ke sumber daya AEK yang tidak diaktifkan. Untuk mengizinkan penyalinan model terenkripsi ke target sebagai tidak terenkripsi, tentukan header x-ms-forms-copy-degrade: true dengan permintaan salin.
"Tidak dapat mengambil informasi untuk sumber daya Kognitif dengan ID...".	Menunjukkan bahwa sumber daya Azure yang ditunjukkan oleh targetResourceId bukan sumber daya Kognitif yang valid atau tidak ada. Untuk mengatasi masalah ini, verifikasi dan terbitkan kembali permintaan salin. Pastikan sumber daya valid dan ada di wilayah yang ditentukan, seperti, westus2

Langkah berikutnya

Dalam panduan ini, Anda mempelajari cara menggunakan Copy API untuk mencadangkan model kustom Anda ke sumber daya Kecerdasan Dokumen sekunder. Selanjutnya, jelajahi dokumen referensi API untuk melihat apa lagi yang dapat Anda lakukan dengan Kecerdasan Dokumen.

• Dokumentasi referensi REST API