Penerjemah v3.0

Artikel
02/14/2024

Yang baru?

Versi 3.0 dari Penerjemah menyediakan API Web berbasis JSON modern. Ini meningkatkan kegunaan dan performa dengan mengonsolidasikan fitur yang ada ke dalam operasi yang lebih sedikit dan menyediakan fitur baru.

Transliterasi untuk mengonversi teks dalam satu bahasa dari satu skrip ke skrip lain.
Terjemahan ke beberapa bahasa dalam satu permintaan.
Deteksi bahasa, terjemahan, dan transliterasi dalam satu permintaan.
Kamus untuk mencari terjemahan alternatif dari istilah, untuk menemukan terjemahan ulang dan contoh yang menampilkan istilah yang digunakan dalam konteks.
Hasil deteksi bahasa yang lebih informatif.

URL Dasar

Permintaan untuk Penerjemah, dalam banyak kasus, ditangani oleh pusat data yang paling dekat dengan tempat permintaan berasal. Jika ada kegagalan pusat data saat menggunakan titik akhir global, permintaan dapat dirutekan di luar geografi.

Untuk memaksa permintaan ditangani dalam geografi tertentu, gunakan titik akhir geografis yang diinginkan. Semua permintaan diproses di antara pusat data dalam geografi.

Geografi	URL Dasar (titik akhir geografis)	Pusat Data
Global (`non-regional`)	api.cognitive.microsofttranslator.com	Pusat data terdekat yang tersedia
Asia Pasifik	api-apc.cognitive.microsofttranslator.com	Korea Selatan, Jepang Timur, Asia Tenggara, dan Australia Timur
Eropa	api-eur.cognitive.microsofttranslator.com	Eropa Utara, Eropa Barat
Amerika Serikat	api-nam.cognitive.microsofttranslator.com	US Timur, US Tengah Selatan, Barat Sentral AS, dan US Barat 2

¹ Pelanggan dengan sumber daya yang terletak di Swiss Utara atau Swiss Barat dapat memastikan bahwa permintaan TEXT API mereka dilayani di Swiss. Untuk memastikan bahwa permintaan ditangani di Swiss, buat sumber daya Penerjemah di Resource regionSwitzerland North atau Switzerland West, lalu gunakan titik akhir kustom sumber daya dalam permintaan API Anda.

Misalnya: Jika Anda membuat sumber daya Penerjemah di portal Azure dengan Resource region sebagai Switzerland North dan nama sumber daya Anda adalah my-swiss-n, maka titik akhir kustom Anda adalah https://my-swiss-n.cognitiveservices.azure.com. Dan sampel permintaan untuk menerjemahkan adalah:

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

²Penerjemah kustom saat ini tidak tersedia di Swiss.

Autentikasi

Berlangganan Penerjemah atau multi-layanan di layanan Azure AI, dan gunakan kunci Anda (tersedia di portal Azure) untuk mengautentikasi.

Ada tiga header yang dapat Anda gunakan untuk mengautentikasi langganan Anda. Tabel ini menjelaskan bagaimana masing-masing digunakan:

Header	Deskripsi
Ocp-Apim-Subscription-Key	Gunakan dengan langganan layanan Azure AI jika Anda meneruskan kunci rahasia Anda. Nilainya adalah kunci rahasia Azure untuk langganan Anda ke Penerjemah.
Otorisasi	Gunakan dengan langganan layanan Azure AI jika Anda melewati token autentikasi. Nilainya adalah Token pembawa: `Bearer <token>`.
Ocp-Apim-Subscription-Region	Gunakan dengan sumber daya penerjemah multi-layanan dan regional. Nilainya adalah wilayah sumber daya penerjemah regional atau multi-layanan. Nilai ini bersifat opsional saat menggunakan sumber daya penerjemah global.

Kunci rahasia

Opsi pertama adalah mengautentikasi menggunakan header Ocp-Apim-Subscription-Key. Tambahkan header Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> ke permintaan Anda.

Mengautentikasi dengan sumber daya global

Saat Anda menggunakan sumber daya penerjemah global, Anda perlu menyertakan satu header untuk memanggil Penerjemah.

Header	Deskripsi
Ocp-Apim-Subscription-Key	Nilainya adalah kunci rahasia Azure untuk langganan Anda ke Penerjemah.

Berikut adalah contoh permintaan untuk memanggil Penerjemah menggunakan sumber daya penerjemah global

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Mengautentikasi dengan sumber daya wilayah

Saat Anda menggunakan sumber daya penerjemah regional, ada dua header yang perlu Anda panggil Penerjemah.

Header	Deskripsi
Ocp-Apim-Subscription-Key	Nilainya adalah kunci rahasia Azure untuk langganan Anda ke Penerjemah.
Ocp-Apim-Subscription-Region	Nilainya adalah wilayah sumber daya penerjemah.

Berikut adalah contoh permintaan untuk memanggil Penerjemah menggunakan sumber daya penerjemah regional

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Mengautentikasi dengan sumber daya Multi-layanan

Sumber daya multi-layanan memungkinkan Anda menggunakan satu kunci API untuk mengautentikasi permintaan untuk beberapa layanan.

Saat menggunakan kunci rahasia multi-layanan, Anda harus menyertakan dua header autentikasi dengan permintaan Anda. Ada 2 header yang Anda perlukan untuk memanggil Penerjemah.

Header	Deskripsi
Ocp-Apim-Subscription-Key	Nilainya adalah kunci rahasia Azure untuk sumber daya multi-layanan Anda.
Ocp-Apim-Subscription-Region	Nilainya adalah wilayah sumber daya multi-layanan.

Wilayah diperlukan untuk langganan Text API multi-layanan. Wilayah yang Anda pilih adalah satu-satunya wilayah yang dapat Anda gunakan untuk terjemahan teks saat menggunakan kunci multi-layanan. Ini harus menjadi wilayah yang sama dengan yang Anda pilih saat mendaftar untuk langganan multi-layanan Anda melalui portal Azure.

Jika Anda melewati kunci rahasia dalam string kueri dengan parameter Subscription-Key, Anda harus menentukan wilayah dengan parameter kueri Subscription-Region.

Mengautentikasi dengan token akses

Atau, Anda dapat menukar kunci rahasia Anda dengan token akses. Token ini disertakan dengan setiap permintaan sebagai header Authorization. Untuk mendapatkan token otorisasi, buat permintaan POST ke URL berikut:

Jenis Sumber Daya	URL layanan autentikasi
Global	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
Regional atau Multi-Layanan	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

Berikut adalah contoh permintaan untuk mendapatkan token yang diberikan kunci rahasia untuk sumber daya global:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

Dan berikut adalah contoh permintaan untuk mendapatkan token yang diberikan kunci rahasia untuk sumber daya regional yang berlokasi di US Tengah:

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

Permintaan yang berhasil menampilkan token akses yang dikodekan sebagai teks biasa dalam isi respons. Token yang valid diteruskan ke layanan Penerjemah sebagai token pembawa dalam Otorisasi.

Authorization: Bearer <Base64-access_token>

Token autentikasi berlaku selama 10 menit. Token harus digunakan kembali saat melakukan beberapa panggilan ke Penerjemah. Namun, jika program Anda mengajukan permintaan ke Penerjemah dalam jangka waktu yang lama, program Anda harus meminta token akses baru secara berkala (misalnya, setiap 8 menit).

Autentikasi dengan ID Microsoft Entra

Penerjemah v3.0 mendukung autentikasi Microsoft Entra, solusi manajemen identitas dan akses berbasis cloud Microsoft. Header otorisasi memungkinkan layanan Penerjemah untuk memvalidasi bahwa klien yang meminta diberi otorisasi untuk menggunakan sumber daya dan untuk menyelesaikan permintaan.

Prasyarat

Pemahaman singkat tentang cara mengautentikasi dengan ID Microsoft Entra.
Pemahaman singkat tentang cara otorisasi akses ke identitas terkelola.

Header

Header	Value
Otorisasi	Nilainya adalah token pembawa akses yang dihasilkan oleh Azure AD. Token pembawa memberikan bukti autentikasi dan memvalidasi otorisasi klien untuk menggunakan sumber daya. Token autentikasi berlaku selama 10 menit dan harus digunakan kembali saat melakukan beberapa panggilan ke Penerjemah. LihatContoh permintaan: 2. Dapatkan token
Ocp-Apim-Subscription-Region	Nilainya adalah wilayah sumber daya penerjemah. Nilai ini bersifat opsional jika sumber daya bersifat global.
Ocp-Apim-ResourceId	Nilainya adalah ID Sumber Daya untuk instans sumber daya Penerjemah Anda. Anda menemukan ID Sumber Daya di portal Azure di Properti → Sumber Daya Penerjemah. Format ID Sumber Daya: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

Halaman properti penerjemah—portal Microsoft Azure

Screenshot:Translator properties page in the Azure portal.

Contoh

Menggunakan titik akhir global

 // Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Menggunakan titik akhir kustom

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Contoh menggunakan identitas terkelola

Penerjemah v3.0 juga mendukung otorisasi akses ke identitas terkelola. Jika identitas terkelola diaktifkan untuk sumber penerjemah, Anda dapat meneruskan token pembawa yang dihasilkan oleh identitas terkelola di header permintaan.

Dengan titik akhir global

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Dengan titik akhir kustom

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

Dukungan Jaringan Virtual

Layanan Penerjemah kini tersedia dengan kemampuan Virtual Network (VNET) di semua wilayah cloud publik Azure. Untuk mengaktifkan Virtual Network, lihatMengonfigurasi jaringan virtual layanan Azure AI.

Setelah Anda mengaktifkan kemampuan ini, Anda harus menggunakan titik akhir kustom untuk memanggil Penerjemah. Anda tidak dapat menggunakan titik akhir penerjemah global ("api.cognitive.microsofttranslator.com") dan tidak dapat mengautentikasi dengan token akses.

Anda dapat menemukan titik akhir kustom setelah membuat sumber daya penerjemah dan mengizinkan akses dari jaringan dan titik akhir perivat yang dipilih.

Navigasikan ke sumber daya Penerjemah Anda di portal Azure.
Pilih Jaringan dari bagian Manajemen Sumber Daya.
Di bawah tab Firewall dan jaringan virtual, pilih Jaringan yang Dipilih dan Titik Akhir Privat.
Pilih Simpan untuk menerapkan perubahan Anda.
Pilih Kunci dan Titik Akhir dari bagian Manajemen Sumber Daya.
Pilih tab Virtual Network .
Tercantum ada titik akhir untuk Terjemahan Teks dan Terjemahan Dokumen.

Header	Deskripsi
Ocp-Apim-Subscription-Key	Nilainya adalah kunci rahasia Azure untuk langganan Anda ke Penerjemah.
Ocp-Apim-Subscription-Region	Nilainya adalah wilayah sumber daya penerjemah. Nilai ini bersifat opsional jika sumber daya adalah `global`

Berikut adalah contoh permintaan untuk memanggil Penerjemah menggunakan titik akhir kustom

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

Kesalahan

Respons kesalahan standar adalah objek JSON dengan pasangan nama/nilai bernama error. Nilainya juga merupakan objek JSON dengan properti:

code: Kode kesalahan yang ditentukan server.
message: String yang memberikan representasi kesalahan yang dapat dibaca manusia.

Misalnya, pelanggan dengan langganan uji coba gratis akan menerima kesalahan berikut setelah kuota gratis habis:

{
  "error": {
    "code":403001,
    "message":"The operation isn't allowed because the subscription has exceeded its free quota."
    }
}

Kode kegagalan adalah 6 digit angka yang menggabungkan kode status HTTP 3 digit diikuti dengan 3 digit angka untuk mengategorikan kesalahan lebih lanjut. Kode kesalahan umum adalah:

Kode	Deskripsi
400000	Salah satu input permintaan tidak valid.
400001	Parameter "scope" tidak valid.
400002	Parameter "category" tidak valid.
400003	Penentu bahasa hilang atau tidak valid.
400004	Penentu skrip target ("Ke skrip") hilang atau tidak valid.
400005	Teks input hilang atau tidak valid.
400006	Kombinasi bahasa dan skrip tidak valid.
400018	Penentu skrip sumber ("Dari skrip") hilang atau tidak valid.
400019	Salah satu bahasa yang ditentukan tidak didukung.
400020	Salah satu elemen dalam larik teks input tidak valid.
400021	Parameter versi API hilang atau tidak valid.
400023	Salah satu pasangan bahasa yang ditentukan tidak valid.
400035	Bahasa sumber (bidang "Dari") tidak valid.
400036	Bahasa target (Bidang “Kepada") hilang atau tidak valid.
400042	Salah satu opsi yang ditentukan (bidang "Opsi") tidak valid.
400043	ID jejak klien (header ClientTraceId atau X-ClientTranceId) hilang atau tidak valid.
400050	Teks input terlalu panjang. Lihat batas permintaan.
400064	Parameter "translation" hilang atau tidak valid.
400070	Jumlah skrip target (parameter ToScript) tidak cocok dengan jumlah bahasa target (parameter To).
400071	Nilai tidak valid untuk TextType.
400072	Array teks input memiliki terlalu banyak elemen.
400073	Parameter skrip tidak valid.
400074	Isi permintaan bukan JSON yang valid.
400075	Pasangan bahasa dan kombinasi kategori tidak valid.
400077	Ukuran permintaan maksimum telah terlampaui. Lihat batas permintaan.
400079	Sistem kustom yang diminta untuk penerjemahan antara dari dan ke bahasa tidak ada.
400080	Transliterasi tidak didukung untuk bahasa atau skrip.
401000	Permintaan ini tidak diotorisasi karena kredensial hilang atau tidak valid.
401015	"Info masuk yang diberikan adalah untuk Speech API. Permintaan ini memerlukan info masuk untuk Text API. Gunakan langganan ke Penerjemah."
403000	Operasi tidak diizinkan.
403001	Operasi ini tidak diizinkan karena langganan telah melampaui kuota gratisnya.
405000	Metode permintaan tidak didukung untuk sumber daya yang diminta.
408001	Sistem penerjemahan yang diminta sedang disiapkan. Coba lagi dalam beberapa menit.
408002	Permintaan waktu tunggu habis di streaming masuk. Klien tidak menghasilkan permintaan di luar batas waktu yang disediakan bagi server untuk menunggu. Klien dapat mengulangi permintaan tanpa modifikasi di lain waktu.
415000	Header Content-Type hilang atau tidak valid.
429000, 429001, 429002	Server menolak permintaan karena klien telah melampaui batas permintaan.
500000	Terjadi kesalahan tidak terduga. Jika kesalahan berlanjut, laporkan dengan tanggal/waktu kesalahan, pengidentifikasi permintaan dari header respons X-RequestId, dan pengidentifikasi klien dari header permintaan X-ClientTraceId.
503000	Layanan untuk sementara tidak tersedia. Coba lagi. Jika kesalahan berlanjut, laporkan dengan tanggal/waktu kesalahan, pengidentifikasi permintaan dari header respons X-RequestId, dan pengidentifikasi klien dari header permintaan X-ClientTraceId.

Metrik

Metrik memungkinkan Anda melihat informasi penggunaan dan ketersediaan penerjemah di portal Azure, di bawah bagian metrik seperti yang ditunjukkan pada cuplikan layar di bawah. Untuk mengetahui informasi selengkapnya, lihat Metrik data dan platform.

Translator Metrics

Tabel ini mencantumkan metrik yang tersedia dengan deskripsi tentang bagaimana metrik tersebut digunakan untuk memantau panggilan API terjemahan.

Metrik	Deskripsi
TotalCalls	Jumlah total panggilan API.
TotalTokenCalls	Jumlah total panggilan API melalui layanan token menggunakan token autentikasi.
SuccessfulCalls	Jumlah panggilan yang berhasil.
TotalErrors	Jumlah panggilan dengan respons kesalahan.
BlockedCalls	Jumlah panggilan yang melebihi batas tarif atau kuota.
ServerErrors	Jumlah panggilan dengan kesalahan internal server (5XX).
ClientErrors	Jumlah panggilan dengan kesalahan sisi klien (4XX).
Latensi	Durasi untuk menyelesaikan permintaan dalam milidetik.
CharactersTranslated	Jumlah total karakter dalam permintaan teks masuk.