Bagikan melalui

Penerjemah v3.0

Apa yang baru?

Penerjemah versi 3.0 menyediakan API Web berbasis JSON modern. Ini meningkatkan kegunaan dan performa dengan mengonsolidasikan fitur yang ada menjadi lebih sedikit operasi 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 suatu istilah, untuk menemukan terjemahan kembali dan contoh yang menunjukkan istilah yang digunakan dalam konteks.
  • Hasil deteksi bahasa yang lebih informatif.

URL Dasar

Permintaan ke Penerjemah adalah, 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: Penerjemah Teks

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, lihatTitik 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 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.

Otentikasi

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

Ada tiga header yang bisa 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 multi-layanan atau regional. Nilai ini bersifat opsional saat menggunakan sumber daya penerjemah global.

Kunci rahasia

Opsi pertama adalah mengautentikasi menggunakan Ocp-Apim-Subscription-Key header. Tambahkan header ke Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> 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 regional

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 dua header yang perlu Anda panggil 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 Microsoft Azure.

Jika Anda meneruskan kunci rahasia dalam string kueri dengan parameter Subscription-Key, maka Anda harus menentukan wilayah dengan parameter Subscription-Regionkueri .

Mengautentikasi dengan token akses

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

Jenis sumber daya URL layanan autentikasi
Mendunia 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 diberi 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 diberi kunci rahasia untuk sumber daya regional yang terletak di AS 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 mengembalikan 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 membuat permintaan ke Penerjemah selama jangka waktu yang lama, maka 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 berwenang untuk menggunakan sumber daya dan untuk menyelesaikan permintaan.

Prasyarat

Header

Kepala Halaman Nilai
Otorisasi Nilainya adalah token pembawa akses yang dihasilkan oleh Azure ACTIVE Directory.
  • 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 Microsoft 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 Anda

// 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 daya 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 Anda

//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 sekarang tersedia dengan kemampuan Virtual Network (VNET) di semua wilayah cloud publik Azure. Untuk mengaktifkan Virtual Network, lihatMengonfigurasi jaringan virtual layanan Azure AI.

Setelah 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 Anda tidak dapat mengautentikasi dengan token akses.

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

  1. Navigasi ke sumber daya Penerjemah Anda di portal Microsoft Azure.

  2. Pilih Jaringan dari bagian Manajemen Sumber Daya.

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

    Cuplikan layar pengaturan jaringan virtual di portal Microsoft 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 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. Nilai ini 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 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 tidak diotorisasi karena kredensial hilang atau tidak valid.
401015 "Kredensial yang disediakan adalah untuk Speech API. Permintaan ini memerlukan kredensial untuk TEXT API. Gunakan langganan untuk Penerjemah."
403000 Operasi tidak diperbolehkan.
403001 Operasi tidak diizinkan karena langganan melebihi 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 Tipe Konten hilang atau tidak valid.
429000, 429001, 429002 Server menolak permintaan karena klien melebihi batas permintaan.
500000 Terjadi kesalahan tak terduga. Jika kesalahan berlanjut, laporkan dengan tanggal/waktu kesalahan, minta pengidentifikasi 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, minta pengidentifikasi dari header respons X-RequestId, dan pengidentifikasi klien dari header permintaan X-ClientTraceId.

Metode pengukuran

Metrik memungkinkan Anda melihat informasi penggunaan dan ketersediaan penerjemah di portal Microsoft Azure. Untuk 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.

Metode pengukuran 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).
Keterlambatan Durasi untuk menyelesaikan permintaan dalam milidetik.
Karakter Diterjemahkan Jumlah total karakter dalam permintaan teks masuk.