Translator v3.0

Makale
04/20/2023

Yenilikler

Translator'ın 3. sürümü 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.
Terimin alternatif çevirilerini aramak, arka çevirileri bulmak 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

Translator'a yönelik istekler çoğu durumda, isteğin kaynaklandığı yere en yakın veri merkezi tarafından işlenir. Genel uç nokta kullanılırken veri merkezi hatası olursa, 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 (`non-regional`)	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

¹ Kuzey İsviçre veya Batı İsviçre'de bulunan bir kaynağı olan müşteriler, Metin API'leri isteklerinin İsviçre içinde sunulduğunda emin olabilir. İsteklerin İsviçre'de işlenmesini sağlamak için Translator kaynağını 'Kaynak bölgesi' 'Kuzey İsviçre' veya 'İsviçre Batı' içinde 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' olan ve kaynak adınız 'my-swiss-n' olan bir Translator kaynağı oluşturuyorsanız, özel uç noktanız "https://my-swiss-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 "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

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

Kimlik Doğrulaması

Azure Bilişsel Hizmetler'de Translator 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 biri nasıl kullanılır açıklanmaktadır:

Üst Bilgiler	Açıklama
Ocp-Apim-Subscription-Key	Gizli anahtarınızı geçiriyorsanız Bilişsel Hizmetler aboneliğiyle kullanın. Değer, Translator aboneliğinizin 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 çevirmen kaynağıyla kullanın. Değer, çok hizmetli veya bölgesel çevirmen 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 bir kaynakla kimlik doğrulaması

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

Üst Bilgiler	Açıklama
Ocp-Apim-Subscription-Key	Değer, Translator aboneliğinizin Azure gizli anahtarıdır.

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

// 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 Translator'ı çağırmanız gereken iki üst bilgi vardır.

Üst Bilgiler	Açıklama
Ocp-Apim-Subscription-Key	Değer, Translator aboneliğinizin Azure gizli anahtarıdır.
Ocp-Apim-Subscription-Region	Değer, çevirmen kaynağının bölgesidir.

Aşağıda, bölgesel çeviri kaynağını kullanarak Translator'ı çağırmak için örnek bir istek verilmiştir

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

Çok hizmetli bir kaynakla 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. Translator'ı çağırmanız gereken iki üst bilgi vardır.

Üst Bilgiler	Açıklama
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. Azure portal aracılığıyla çok hizmetli aboneliğinize kaydolduğunda 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 almak için örnek istekler 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ç, Translator hizmetine Yetkilendirmede taşıyıcı belirteç olarak geçirilir.

Authorization: Bearer <Base64-access_token>

Kimlik doğrulama belirteci 10 dakika boyunca geçerlidir. Translator'a birden çok çağrı yapılırken belirteç yeniden kullanılmalıdır. Ancak, programınız uzun bir süre boyunca Translator'a 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)

Translator 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 Translator hizmetinin, istekte bulunan istemcinin kaynağı kullanma ve isteği tamamlama yetkisine sahip olduğunu doğrulamasını sağlar.

Önkoşullar

Azure Active Directory ile kimlik doğrulamasının nasıl yapılacağını kısa bir şekilde anlama.
Yönetilen kimliklere erişimi yetkilendirme hakkında kısa bir bilgi.

Üst Bilgiler

Üst bilgi	Değer
Yetkilendirme	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 Translator'a birden çok çağrı yapılırken yeniden kullanılmalıdır. Bkz. Örnek istek: 2. Belirteç alma
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, Translator kaynak örneğinizin Kaynak Kimliğidir. Kaynak Kimliğini Translator Kaynak → Özellikleri'ndeki Azure portal bulabilirsiniz. Kaynak Kimliği biçimi: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

Translator özellik sayfası—Azure portal

ekran görüntüsü:Azure portal Translator özellikleri sayfası.

Ö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

Translator 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

Translator 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 Translator'ı ç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.

Azure portal Translator kaynağınıza gidin.
Kaynak Yönetimi bölümünden Ağ'ı seçin.
Güvenlik duvarları ve sanal ağlar sekmesinde Seçili Ağlar ve Özel Uç Noktalar'ı seçin.
Değişikliklerinizi uygulamak için Kaydet’i seçin.
Kaynak Yönetimi bölümünde Anahtarlar ve Uç Nokta'ya tıklayın.
Sanal Ağ sekmesini seçin.
Metin Çevirisi ve Belge Çevirisi için uç noktalar listelenir.

Üst Bilgiler	Açıklama
Ocp-Apim-Subscription-Key	Değer, Translator aboneliğinizin 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 Translator'ı ç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ı ("To betiği") eksik veya geçersiz.
400005	Giriş metni eksik veya geçersiz.
400006	Dil ve betiğin birleşimi geçerli değil.
400018	Kaynak betik tanımlayıcısı ("From betiği") 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 ("From" alanı) geçerli değil.
400036	Hedef dil ("To" alanı) eksik veya geçersiz.
400042	Belirtilen seçeneklerden biri ("Options" 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	“Translation” parametresi eksik veya geçersiz.
400070	Hedef betik 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	Dilden dile çeviri için istenen özel sistem yok.
400080	Dil veya komut dosyası için harf çevirisi 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. Translator aboneliğini kullanın."
403000	İşleme izin verilmiyor.
403001	Abonelik ücretsiz kotasını aştığından işleme izin verilmiyor.
405000	İstenen kaynak için istek yöntemi 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	İçerik Türü ü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 çevirinin kullanım ve kullanılabilirlik bilgilerini görüntülemenizi sağlar. Daha fazla bilgi için bkz. Veri ve platform ölçümleri.

Translator Ölçümleri

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	Açıklama
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ıların sayısı.
TotalErrors	Hata yanıtı olan çağrıların sayısı.
BlockedCalls	Hız veya kota sınırını aşan çağrı sayısı.
ServerErrors	Sunucu iç hatası (5XX) içeren çağrıların sayısı.
ClientErrors	İstemci tarafı hatası (4XX) içeren çağrıların sayısı.
Gecikme süresi	İsteğin milisaniye cinsinden tamamlanma süresi.
Çevrilen Karakterler	Gelen metin isteğindeki toplam karakter sayısı.