Çeviri v3.0

Makale
02/14/2024

Yenilikler

Çeviri sürüm 3.0, 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

Ç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 (`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ğundan emin olabilir. İsteklerin İsviçre'de işlenmesini sağlamak için veya Switzerland Westiçinde Çeviri kaynağı Resource regionSwitzerland North 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 Çeviri kaynağı oluşturursanız ve kaynak adınız isemy-swiss-n, özel uç noktanız olurhttps://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 yapay zeka hizmetlerinde Çeviri 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, aboneliğinizin Çeviri için 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, Çeviri çağırmak için bir üst bilgi eklemeniz gerekir.

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

Genel çeviri kaynağını kullanarak Çeviri çağırmak için örnek bir istek aşağıda 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, Çeviri çağırmanız gereken iki üst bilgi vardır.

Üst Bilgiler	Açıklama
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?'}]"

Ç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. Çeviri ç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
Genel	`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ç, 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.

Microsoft Entra Kimliği ile kimlik doğrulaması

Çeviri 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, Çeviri hizmetinin istekte bulunan istemcinin kaynağı kullanma yetkisi olduğunu doğrulamasını ve isteği tamamlamasını 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 Çeviri 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, Çeviri kaynak örneğinizin Kaynak Kimliğidir. Kaynak Kimliğini Azure portalında Ç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 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

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

Bu özelliği açtığınızda, Çeviri ç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 Çeviri 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, aboneliğinizin Çeviri için 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 Çeviri ç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-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. Çeviri için bir abonelik 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 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	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ı.