Translator v3.0

Makale
09/01/2024

Yenilikler

Translator'ın 3.0 sürümü modern bir JSON tabanlı Web API'sini sağlar. Mevcut özellikleri daha az işlemle 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 çeviri.
Tek bir istekte birden çok dile çeviri.
Tek bir istekte dil algılama, çeviri ve çeviri.
Terimlerin alternatif çevirilerini aramak, arka ç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

Translator'a yönelik istekler çoğu durumda, isteğin geldiği 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.

✔️ Özellik: Translator Metin Çevirisi

Hizmet uç noktası	İstek işleme veri merkezi
Genel (önerilen): `api.cognitive.microsofttranslator.com`	En yakın kullanılabilir veri merkezi.
Amerika: `api-nam.cognitive.microsofttranslator.com`	Doğu ABD 2 • Batı ABD 2
Asya Pasifik `api-apc.cognitive.microsofttranslator.com`:	Doğu Japonya • Güneydoğu Asya
Avrupa (İsviçre hariç): `api-eur.cognitive.microsofttranslator.com`	Orta Fransa • Batı Avrupa
İsviçre: Daha fazla bilgi için bkz. İsviçre hizmet uç noktaları.	kuzey İsviçre • İsviçre Batı

İsviçre hizmet uç noktaları

Kuzey İsviçre veya Batı İsviçre'de bulunan bir kaynağı olan müşteriler, Metin API'leri isteklerinin İsviçre içinde sunulduğundan emin olabilir. İsteklerin İsviçre'de işlenmesini sağlamak için veya Switzerland Westiçinde Resource region Switzerland North Translator kaynağını oluşturun ve ardından API isteklerinizde kaynağın özel uç noktasını kullanın.

Örneğin: Azure portalında Resource region ile Switzerland North bir Translator kaynağı oluşturursanız ve kaynak adınız ise my-swiss-n, özel uç noktanız olur 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 Çevirmen şu anda İsviçre'de kullanılamıyor.

Kimlik Doğrulaması

Azure AI hizmetlerinde Translator'a veya çoklu hizmete abone olun ve kimliğinizi doğrulamak için anahtarınızı (Azure portalında 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	Açıklama
Ocp-Apim-Subscription-Key	Gizli anahtarınızı geçiriyorsanız Azure AI hizmetleri aboneliğiyle kullanın. Değer, Translator aboneliğinizin Azure gizli anahtarıdır.
Yetkilendirme	Kimlik doğrulama belirteci geçiriyorsanız Azure AI hizmetleri aboneliğiyle kullanın. Değer Taşıyıcı belirtecidir: `Bearer <token>`.
Ocp-Apim-Subscription-Region	Çok hizmetli ve bölgesel çeviri kaynağı ile kullanın. Değer, çok hizmetli veya bölgesel çevirmen kaynağının bölgesidir. Genel çeviri 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 bilgiyi isteğinize ekleyin.

Genel 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ş.

// 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 bir 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 çevirmen kaynağını kullanarak Translator'ı ç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?'}]"

Çok hizmetli bir kaynakla kimlik doğrulaması

Çok hizmetli bir kaynak, 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ın Azure gizli anahtarıdır.
Ocp-Apim-Subscription-Region	Değer, çok hizmetli kaynağın bölgesidir.

Çok hizmetli Metin API'si 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. Bu bölge, Azure portalı aracılığıyla çok hizmetli aboneliğinize kaydolduğunda seçtiğiniz bölge olmalıdır.

Sorgu dizesindeki 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
Global	`https://api.cognitive.microsoft.com/sts/v1.0/issueToken`
Bölgesel veya Çok Hizmetli	`https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken`

Genel 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://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 Yetkilendirme'de taşıyıcı belirteç olarak geçirilir.

Authorization: Bearer <Base64-access_token>

Kimlik doğrulama belirteci 10 dakika geçerlidir. Translator'a birden çok çağrı yapılırken belirtecin yeniden kullanılması gerekir. 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.

Microsoft Entra Kimliği ile kimlik doğrulaması

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

Önkoşullar

Microsoft Entra Id ile kimlik doğrulaması hakkında kısa bir bilgi.
Yönetilen kimliklere erişimi yetkilendirme hakkında kısa bir bilgi.

Ü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 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 genelse bu değer isteğe bağlıdır.
Ocp-Apim-ResourceId	Değer, Translator kaynak örneğinizin Kaynak Kimliğidir. Kaynak Kimliğini Azure portalında Translator Kaynak → Özellikleri bölümünde 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ında Translator özellikleri sayfası.

Önemli

Hizmet sorumlusuna Bilişsel Hizmetler Kullanıcı rolü atayın. Bu rolü atayarak, Translator kaynağına hizmet sorumlusu erişimi verirsiniz.

Ö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 bilgisine 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 AI hizmetleri sanal ağlarını yapılandırma.

Bu özelliği açtığınızda Translator'ı çağırmak için özel uç noktayı kullanmanız gerekir. Genel çeviri uç noktasını ("api.cognitive.microsofttranslator.com") kullanamazsınız 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ında 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.
Yaptığınız değişiklikleri 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 listelenmiştir.

Ü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 şu durumdaysa 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ş.

// 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 özelliklere sahip bir JSON nesnesidir:

code: Sunucu tanımlı bir hata kodu.
message: Hatanın insan tarafından okunabilir bir gösterimini 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-ClientTraceId ü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. Yeniden deneyin. 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 Ölçümler bölümünde Azure portalda çeviri 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 toplam API çağrısı sayısı.
SuccessfulCalls	Başarılı çağrı sayısı.
TotalErrors	Hata yanıtı içeren ç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) ile ç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ı.

Aracılığıyla paylaş