Bagikan melalui

Penerjemah v3.0

  • Artikel

Apa yang baru?

Penerjemah versi 3.0 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.

✔️ Fitur: Teks Penerjemah

Titik akhir layanan Meminta pusat data pemrosesan
Global (disarankan):
api.cognitive.microsofttranslator.com		 Pusat data terdekat yang tersedia.
Amerika:
api-nam.cognitive.microsofttranslator.com		 US Timur 2 • US Barat 2
Asia Pasifik
api-apc.cognitive.microsofttranslator.com:		 Jepang Timur • Asia Tenggara
Eropa (kecuali Swiss):
api-eur.cognitive.microsofttranslator.com		 Prancis Tengah • Eropa Barat
Swiss:
Untuk informasi selengkapnya, lihat Titik akhir layanan Swiss.		 Swiss Utara • Swiss Barat

Titik akhir layanan Swiss

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 region Switzerland 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.
Authorization 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

Header

Header Nilai
Authorization 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.
    • Lihat Contoh 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

Cuplikan layar:Halaman properti penerjemah di portal Microsoft Azure.

Penting

Tetapkan peran Pengguna Cognitive Services ke perwakilan layanan. Dengan menetapkan peran ini, Anda memberikan akses perwakilan layanan ke sumber daya Penerjemah.

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, lihat Mengonfigurasi 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.

  1. Navigasikan ke sumber daya Penerjemah Anda di portal Azure.

  2. Pilih Jaringan dari bagian Manajemen Sumber Daya.

  3. Di bawah tab Firewall dan jaringan virtual, pilih Jaringan yang Dipilih dan Titik Akhir Privat.

    Cuplikan layar pengaturan jaringan virtual di portal Azure.

  4. Pilih Simpan untuk menerapkan perubahan Anda.

  5. Pilih Kunci dan Titik Akhir dari bagian Manajemen Sumber Daya.

  6. Pilih tab Virtual Network .

  7. Tercantum ada titik akhir untuk Terjemahan Teks dan Terjemahan Dokumen.

    Cuplikan layar titik akhir jaringan virtual.

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 pelacakan klien (bidang ClientTraceId atau header X-ClientTraceId) 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.

Metrik Penerjemah

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.