Çeviri v3.0

Yenilikler

Çeviri sürüm 3, modern bir JSON tabanlı Web API'sini sağlar. Mevcut özellikleri daha az işlemde birleştirerek kullanılabilirliği ve performansı artırır ve yeni özellikler sağlar.

  • Bir dildeki metni bir betikten başka bir betike dönüştürmek için alfabeye çevirme.
  • Tek bir istekte birden çok dile çeviri.
  • Tek bir istekte dil algılama, çeviri ve alfabeye çevirme.
  • Bir terimin alternatif çevirilerini aramak, geri çevirileri ve bağlam içinde kullanılan terimleri gösteren örnekleri bulmak için sözlük.
  • Daha bilgilendirici dil algılama sonuçları.

Temel URL'ler

Çeviri istekleri çoğu durumda, isteğin kaynaklandığı yere en yakın veri merkezi tarafından işlenir. Genel uç nokta kullanılırken bir veri merkezi hatası varsa, istek coğrafyanın dışına yönlendirilebilir.

İsteğin belirli bir coğrafyada işlenmesini zorlamak için istenen coğrafi uç noktayı kullanın. Tüm istekler coğrafyadaki veri merkezleri arasında işlenir.

Coğrafya Temel URL (coğrafi uç nokta) Veri merkezleri
Genel (bölgesel olmayan) api.cognitive.microsofttranslator.com Kullanılabilir en yakın veri merkezi
Asya Pasifik api-apc.cognitive.microsofttranslator.com Güney Kore, Doğu Japonya, Güneydoğu Asya ve Doğu Avustralya
Avrupa api-eur.cognitive.microsofttranslator.com Kuzey Avrupa, Batı Avrupa
Birleşik Devletler api-nam.cognitive.microsofttranslator.com Doğu ABD, Orta Güney ABD, Orta Batı ABD ve Batı ABD 2

1 Kuzey İsviçre veya Batı İsviçre'de bulunan bir kaynağa sahip müşteriler Metin API'leri isteklerinin İsviçre'de sunulduğuna emin olabilir. İsteklerin İsviçre'de işlenmesini sağlamak için 'Kaynak bölgesi' 'Kuzey İsviçre' veya 'İsviçre Batı' içinde Çeviri kaynağı oluşturun, ardından API isteklerinizde kaynağın özel uç noktasını kullanın. Örneğin: Azure portal'da 'Kaynak bölgesi' 'İsviçre Kuzey' olarak ve kaynak adınız 'my-ch-n' olan bir Çeviri kaynağı oluşturuyorsanız, özel uç noktanız "https://my-ch-n.cognitiveservices.azure.com". Çeviri için örnek bir istek de şu şekildedir:

// Pass secret key and region using headers to a custom endpoint
curl -X POST " my-ch-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

2 Özel Çeviri şu anda İsviçre'de kullanılamıyor.

Kimlik Doğrulaması

Azure Bilişsel Hizmetler'de Çeviri veya Bilişsel Hizmetler çoklu hizmetine abone olun ve kimliğinizi doğrulamak için anahtarınızı (Azure portal kullanılabilir) kullanın.

Aboneliğinizin kimliğini doğrulamak için kullanabileceğiniz üç üst bilgi vardır. Bu tabloda her birinin nasıl kullanıldığı açıklanmaktadır:

Üst Bilgiler Description
Ocp-Apim-Subscription-Key Gizli anahtarınızı geçiriyorsanız Bilişsel Hizmetler aboneliğiyle kullanın.
Değer, aboneliğinizin Çeviri için Azure gizli anahtarıdır.
Yetkilendirme Kimlik doğrulama belirteci geçiriyorsanız Bilişsel Hizmetler aboneliğiyle kullanın.
Değer Taşıyıcı belirtecidir: Bearer <token>.
Ocp-Apim-Subscription-Region Bilişsel Hizmetler çok hizmetli ve bölgesel çeviri kaynağı ile kullanın.
Değer, çok hizmetli veya bölgesel çeviri kaynağının bölgesidir. Genel çevirmen kaynağı kullanılırken bu değer isteğe bağlıdır.

Gizli anahtar

İlk seçenek, üst bilgiyi kullanarak Ocp-Apim-Subscription-Key kimlik doğrulaması yapmaktır. Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> üst bilgisini isteğinize ekleyin.

Genel kaynakla kimlik doğrulaması

Genel çeviri kaynağı kullandığınızda, Çeviri çağırmak için bir üst bilgi eklemeniz gerekir.

Üst Bilgiler Description
Ocp-Apim-Subscription-Key Değer, aboneliğinizin Çeviri için Azure gizli anahtarıdır.

Aşağıda genel çevirmen kaynağını kullanarak Çeviri çağırmak için örnek bir istek verilmiş

// 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?'}]"

Bölgesel kaynakla kimlik doğrulaması

Bölgesel bir çevirmen kaynağı kullandığınızda. Çeviri çağırmanız gereken iki üst bilgi vardır.

Üst Bilgiler Description
Ocp-Apim-Subscription-Key Değer, aboneliğinizin Çeviri için Azure gizli anahtarıdır.
Ocp-Apim-Subscription-Region Değer, çevirmen kaynağının bölgesidir.

Aşağıda bölgesel çevirmen kaynağını kullanarak Çeviri çağırmak için örnek bir istek verilmiş

// 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?'}]"

Çoklu hizmet kaynağıyla kimlik doğrulaması

Bilişsel Hizmet çoklu hizmet kaynağı, birden çok hizmet için isteklerin kimliğini doğrulamak için tek bir API anahtarı kullanmanıza olanak tanır.

Çok hizmetli gizli anahtar kullandığınızda, isteğinize iki kimlik doğrulama üst bilgisi eklemeniz gerekir. Çeviri çağırmanız gereken iki üst bilgi vardır.

Üst Bilgiler Description
Ocp-Apim-Subscription-Key Değer, çok hizmetli kaynağınız için Azure gizli anahtarıdır.
Ocp-Apim-Subscription-Region Değer, çok hizmetli kaynağın bölgesidir.

Çok hizmetli Metin API'sinin aboneliği için bölge gereklidir. Seçtiğiniz bölge, çok hizmetli anahtarı kullanırken metin çevirisi için kullanabileceğiniz tek bölgedir ve Azure portal aracılığıyla çok hizmetli aboneliğinize kaydolduğunuz sırada seçtiğiniz bölge olmalıdır.

Sorgu dizesinde gizli anahtarı parametresiyle Subscription-Keygeçirirseniz sorgu parametresiyle Subscription-Regionbölgeyi belirtmeniz gerekir.

Erişim belirteci ile kimlik doğrulaması

Alternatif olarak, gizli anahtarınızı erişim belirteci ile değiştirebilirsiniz. Bu belirteç her isteğe üst bilgi olarak Authorization eklenir. Yetkilendirme belirteci almak için aşağıdaki URL'ye bir POST istek gönderin:

Kaynak türü Kimlik doğrulama hizmeti URL'si
Genel https://api.cognitive.microsoft.com/sts/v1.0/issueToken
Bölgesel veya Çoklu Hizmet https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken

Aşağıda genel bir kaynak için gizli anahtar verilen bir belirteci alma isteklerine örnek verilmiştir:

// 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>'

Orta ABD'de bulunan bölgesel bir kaynak için gizli anahtar verilen bir belirteci alma istekleri aşağıda verilmiştir:

// 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>"

Başarılı bir istek, kodlanmış erişim belirtecini yanıt gövdesinde düz metin olarak döndürür. Geçerli belirteç, yetkilendirmede taşıyıcı belirteç olarak Çeviri hizmetine geçirilir.

Authorization: Bearer <Base64-access_token>

Kimlik doğrulama belirteci 10 dakika geçerlidir. belirteç, Çeviri birden çok çağrı yapılırken yeniden kullanılmalıdır. Ancak, programınız uzun bir süre boyunca Çeviri istekte bulunursa, programınızın düzenli aralıklarla (örneğin, her 8 dakikada bir) yeni bir erişim belirteci istemesi gerekir.

Azure Active Directory ile kimlik doğrulaması (Azure AD)

Çeviri v3.0, Microsoft'un bulut tabanlı kimlik ve erişim yönetimi çözümü olan Azure AD kimlik doğrulamasını destekler. Yetkilendirme üst bilgileri, Çeviri hizmetinin istekte bulunan istemcinin kaynağı kullanma ve isteği tamamlama yetkisi olduğunu doğrulamasını sağlar.

Önkoşullar

Üst Bilgiler

Üst bilgi Değer
Yetkilendirme Bu değer, Azure AD tarafından oluşturulan bir erişim taşıyıcı belirtecidir .
  • Taşıyıcı belirteci kimlik doğrulaması kanıtı sağlar ve istemcinin kaynağı kullanma yetkisini doğrular.
  • Kimlik doğrulama belirteci 10 dakika geçerlidir ve Çeviri birden çok çağrı yapılırken yeniden kullanılmalıdır.
  • Yukarıdaki Bkz. Erişim belirteci ile kimlik doğrulama.
Ocp-Apim-Subscription-Region Değer, çevirmen kaynağının bölgesidir.
  • Kaynak genel ise bu değer isteğe bağlıdır.
Ocp-Apim-ResourceId Değer, Çeviri kaynak örneğinizin Kaynak Kimliğidir.
  • Kaynak Kimliğini Azure portal Çeviri Kaynak → Özellikleri'nde bulabilirsiniz.
  • Kaynak Kimliği biçimi:
    /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/
Çeviri özellik sayfası— Azure portal

Screenshot:Translator properties page in the Azure portal.

Örnekler

Genel uç noktayı kullanma

 // 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.'}]"

Özel uç noktanızı kullanma

// 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.'}]"

Yönetilen kimlikleri kullanan örnekler

Çeviri v3.0, yönetilen kimliklere erişimi yetkilendirmeyi de destekler. Bir çevirmen kaynağı için yönetilen kimlik etkinleştirildiyse, yönetilen kimlik tarafından oluşturulan taşıyıcı belirteci istek üst bilgisinde geçirebilirsiniz.

Genel uç nokta ile

// 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.'}]"

Özel uç noktanızla

//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.'}]"

Sanal Ağ desteği

Çeviri hizmeti artık Azure genel bulutunun tüm bölgelerinde Sanal Ağ (VNET) özellikleriyle kullanılabilir. Sanal Ağ etkinleştirmek için bkz. Azure Bilişsel Hizmetler Sanal Ağlarını Yapılandırma.

Bu özelliği etkinleştirdikten sonra, Çeviri çağırmak için özel uç noktayı kullanmanız gerekir. Genel çeviri uç noktasını ("api.cognitive.microsofttranslator.com") kullanamaz ve erişim belirteci ile kimlik doğrulaması yapamazsınız.

Bir çevirmen kaynağı oluşturduktan ve seçili ağlardan ve özel uç noktalardan erişime izin verdikten sonra özel uç noktayı bulabilirsiniz.

Üst Bilgiler Description
Ocp-Apim-Subscription-Key Değer, aboneliğinizin Çeviri için Azure gizli anahtarıdır.
Ocp-Apim-Subscription-Region Değer, çevirmen kaynağının bölgesidir. Kaynak isteğe bağlıysa bu değer isteğe bağlıdır global

Özel uç noktayı kullanarak Çeviri çağırmak için örnek bir istek aşağıda verilmiştir

// 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?'}]"

Hatalar

Standart hata yanıtı, adlı errorad/değer çifti olan bir JSON nesnesidir. Değer ayrıca özellikleri olan bir JSON nesnesidir:

  • code: Sunucu tanımlı bir hata kodu.
  • message: Hatanın insan tarafından okunabilir bir temsilini veren bir dize.

Örneğin, ücretsiz deneme aboneliği olan bir müşteri, ücretsiz kota tükendiğinde aşağıdaki hatayı alır:

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

Hata kodu, hatayı daha fazla kategorilere ayırmak için 3 basamaklı HTTP durum kodunu ve ardından 3 basamaklı bir sayıyı birleştiren 6 basamaklı bir sayıdır. Yaygın hata kodları şunlardır:

Kod Description
400000 İstek girişlerinden biri geçerli değil.
400001 "scope" parametresi geçersiz.
400002 "category" parametresi geçersiz.
400003 Dil belirtici eksik veya geçersiz.
400004 Hedef betik tanımlayıcısı ("Kime betiği") eksik veya geçersiz.
400005 Giriş metni eksik veya geçersiz.
400006 Dil ve betik birleşimi geçerli değil.
400018 Kaynak betik tanımlayıcısı ("Kaynak betik") eksik veya geçersiz.
400019 Belirtilen dillerden biri desteklenmiyor.
400020 Giriş metni dizisindeki öğelerden biri geçerli değil.
400021 API sürüm parametresi eksik veya geçersiz.
400023 Belirtilen dil çiftlerinden biri geçerli değil.
400035 Kaynak dil ("Kimden" alanı) geçerli değil.
400036 Hedef dil ("Kime" alanı) eksik veya geçersiz.
400042 Belirtilen seçeneklerden biri ("Seçenekler" alanı) geçerli değil.
400043 İstemci izleme kimliği (ClientTraceId alanı veya X-ClientTranceId üst bilgisi) eksik veya geçersiz.
400050 Giriş metni çok uzun. İstek sınırlarını görüntüleyin.
400064 "Çeviri" parametresi eksik veya geçersiz.
400070 Hedef betiklerin sayısı (ToScript parametresi), hedef dil sayısıyla (To parametresi) eşleşmiyor.
400071 Değer TextType için geçerli değil.
400072 Giriş metni dizisinde çok fazla öğe var.
400073 Betik parametresi geçerli değil.
400074 İsteğin gövdesi geçerli JSON değil.
400075 Dil çifti ve kategori bileşimi geçerli değil.
400077 İstek boyutu üst sınırı aşıldı. İstek sınırlarını görüntüleyin.
400079 ile dili arasında çeviri için istenen özel sistem yok.
400080 Dil veya betik için başka alfabeye çevirme desteklenmez.
401000 Kimlik bilgileri eksik veya geçersiz olduğundan istek yetkilendirilmedi.
401015 "Sağlanan kimlik bilgileri Konuşma API'sine yöneliktir. Bu istek, Metin API'sinin kimlik bilgilerini gerektirir. Çeviri için abonelik kullanın."
403000 İşleme izin verilmiyor.
403001 Abonelik ücretsiz kotasını aştığından işleme izin verilmiyor.
405000 İstek yöntemi istenen kaynak için desteklenmiyor.
408001 İstenen çeviri sistemi hazırlanıyor. Birkaç dakika içinde yeniden deneyin.
408002 İstek, gelen akışı beklerken zaman aşımına uğradı. İstemci, sunucunun beklemeye hazır olduğu süre içinde bir istek oluşturmadı. İstemci daha sonra değişiklik yapmadan isteği tekrar edebilir.
415000 Content-Type üst bilgisi eksik veya geçersiz.
429000, 429001, 429002 İstemci istek sınırlarını aştığı için sunucu isteği reddetti.
500000 Beklenmeyen bir hata oluştu. Hata devam ederse, hatanın tarih/saati, yanıt üst bilgisi X-RequestId'den istek tanımlayıcısı ve X-ClientTraceId istek üst bilgisinden istemci tanımlayıcısı ile bildirin.
503000 Hizmet geçici olarak kullanılamıyor. Yeni -den deneme. Hata devam ederse, hatanın tarih/saati, yanıt üst bilgisi X-RequestId'den istek tanımlayıcısı ve X-ClientTraceId istek üst bilgisinden istemci tanımlayıcısı ile bildirin.

Ölçümler

Ölçümler, aşağıdaki ekran görüntüsünde gösterildiği gibi Azure portal ölçümler bölümünde çevirici kullanımı ve kullanılabilirlik bilgilerini görüntülemenizi sağlar. Daha fazla bilgi için bkz . Veri ve platform ölçümleri.

Translator Metrics

Bu tabloda, çeviri API'si çağrılarını izlemek için nasıl kullanıldıklarına yönelik açıklama içeren kullanılabilir ölçümler listelenmektedir.

Ölçümler Description
TotalCalls Toplam API çağrısı sayısı.
TotalTokenCalls Kimlik doğrulama belirtecini kullanan belirteç hizmeti aracılığıyla yapılan API çağrılarının toplam sayısı.
SuccessfulCalls Başarılı çağrı sayısı.
TotalErrors Hata yanıtı olan çağrı sayısı.
BlockedCalls Hız veya kota sınırını aşan çağrı sayısı.
ServerErrors Sunucu iç hatası (5XX) ile çağrı sayısı.
ClientErrors İstemci tarafı hatası (4XX) içeren çağrı sayısı.
Gecikme süresi İsteğin tamamlanması için milisaniye cinsinden süre.
Çevrilen Karakterler Gelen metin isteğindeki toplam karakter sayısı.