REST API'lerini program aracılığıyla kullanma
Belge Çevirisi, Azure AI Translator hizmetinin bulut tabanlı bir özelliğidir. Belge Çevirisi API'sini kullanarak tüm belgeleri desteklenen dillerde ve çeşitli dosya biçimlerinde zaman uyumsuz olarak çevirebilir ve kaynak belge yapısını ve metin biçimlendirmesini koruyabilirsiniz. Bu nasıl yapılır kılavuzunda Belge Çevirisi API'lerini tercih ettiğiniz bir programlama dili ve HTTP REST API'si ile kullanmayı öğreneceksiniz.
Önkoşullar
Not
Genellikle, Azure portalında bir Azure AI kaynağı oluşturduğunuzda, çok hizmetli bir anahtar veya tek hizmetli anahtar oluşturma seçeneğiniz vardır. Ancak, Belge Çevirisi şu anda yalnızca Translator (tek hizmetli) kaynağında desteklenir ve Azure AI hizmetleri (çok hizmetli) kaynağına dahil değildir .
Belge Çevirisi, S1 Standart Hizmet Planı (Kullandıkça öde) ve C2, C3, C4 ve D3 Toplu İndirim Planlarında desteklenir. Bkz. Azure AI hizmetleri fiyatlandırması— Translator.
Başlamak için gerekli olanlar:
Etkin bir Azure hesabı. Hesabınız yoksa ücretsiz bir hesap oluşturabilirsiniz
bir Azure Blob Depolama hesabı. Ayrıca kaynak ve hedef dosyalarınız için Azure Blob Depolama hesabınızda kapsayıcılar oluşturmanız gerekir:
- Kaynak kapsayıcı. Bu kapsayıcı, dosyalarınızı çeviri için karşıya yüklediğiniz yerdir (gerekli).
- Hedef kapsayıcı. Bu kapsayıcı, çevrilen dosyalarınızın depolandığı yerdir (gereklidir).
Tek hizmetli Translator kaynağı (çok hizmetli bir Azure AI hizmetleri kaynağı değil):
Translator proje ve örnek ayrıntıları alanlarını aşağıdaki gibi tamamlayın:
Abonelik. Kullanılabilir Azure aboneliklerinizden birini seçin.
Kaynak Grubu. Yeni bir kaynak grubu oluşturabilir veya kaynağınızı aynı yaşam döngüsünü, izinleri ve ilkeleri paylaşan önceden var olan bir kaynak grubuna ekleyebilirsiniz.
Kaynak Bölgesi. İşletmeniz veya uygulamanız belirli bir bölge gerektirmediği sürece Genel'i seçin. Kimlik doğrulaması için sistem tarafından atanan yönetilen kimlik kullanmayı planlıyorsanız Batı ABD gibi bir coğrafi bölge seçin.
Adı. Kaynağınız için seçtiğiniz adı girin. Seçtiğiniz ad Azure içinde benzersiz olmalıdır.
Not
Belge Çevirisi için özel bir etki alanı uç noktası gerekir. Ad alanına girdiğiniz değer, uç noktanız için özel etki alanı adı parametresi olacaktır.
Fiyatlandırma katmanı. Belge Çevirisi ücretsiz katmanda desteklenmez. Hizmeti denemek için Standart S1'i seçin.
Gözden geçir + Oluştur’u seçin.
Hizmet koşullarını gözden geçirin ve kaynağınızı dağıtmak için Oluştur'u seçin.
Kaynağınız başarıyla dağıtıldıktan sonra anahtarınızı ve uç noktanızı almak için Kaynağa git'i seçin.
Anahtarınızı ve özel etki alanı uç noktanızı alma
- Translator hizmetine yönelik istekler, erişimin kimliğini doğrulamak için salt okunur bir anahtar ve özel uç nokta gerektirir. Özel etki alanı uç noktası kaynak adınız, konak adınız ve Translator alt dizinlerinizle biçimlendirilmiş bir URL'dir ve Azure portalında kullanılabilir.
Yeni bir kaynak oluşturduysanız, dağıtıldıktan sonra Kaynağa git'i seçin. Mevcut bir Belge Çevirisi kaynağınız varsa doğrudan kaynak sayfanıza gidin.
Sol rayda, Kaynak Yönetimi'nin altında Anahtarlar ve Uç Nokta'yı seçin.
ve öğelerinizi
key
document translation endpoint
kopyalayıp Microsoft Not Defteri gibi uygun bir konuma yapıştırın. API çağrısı yapmak için yalnızca bir anahtar gerekir.Belge
key
Çevirisi hizmetinde isteğinizin kimliğini doğrulamak için siz vedocument translation endpoint
kod örneklerine girin.
Anahtarınızı alın
Translator hizmetine yönelik istekler, erişimin kimliğini doğrulamak için salt okunur bir anahtar gerektirir.
- Yeni bir kaynak oluşturduysanız, dağıtıldıktan sonra Kaynağa git'i seçin. Mevcut bir Belge Çevirisi kaynağınız varsa doğrudan kaynak sayfanıza gidin.
- Sol rayda, Kaynak Yönetimi'nin altında Anahtarlar ve Uç Nokta'yı seçin.
- Anahtarınızı kopyalayıp Microsoft Not Defteri gibi uygun bir konuma yapıştırın.
- Belge Çevirisi hizmetine isteğinizin kimliğini doğrulamak için bunu kod örneğine yapıştırırsınız.
Azure Blob Depolama kapsayıcıları oluşturma
Kaynak ve hedef dosyalar için Azure Blob Depolama hesabınızda kapsayıcılar oluşturmanız gerekir.
- Kaynak kapsayıcı. Bu kapsayıcı, dosyalarınızı çeviri için karşıya yüklediğiniz yerdir (gerekli).
- Hedef kapsayıcı. Bu kapsayıcı, çevrilen dosyalarınızın depolandığı yerdir (gereklidir).
Not
Belge Çevirisi, hedef kapsayıcılarda blob olarak (ayrı sözlük kapsayıcıları değil) sözlükleri destekler. Özel bir sözlük eklemek istiyorsanız, bunu hedef kapsayıcıya ekleyin ve isteğine glossaryUrl
ekleyin. Çeviri dil çifti sözlükte yoksa uygulanmaz. Bkz. Özel sözlük kullanarak belgeleri çevirme
Belge Çevirisi için SAS erişim belirteçleri oluşturma
sourceUrl
, targetUrl
ve isteğe bağlıglossaryUrl
, sorgu dizesi olarak eklenmiş bir Paylaşılan Erişim İmzası (SAS) belirteci içermelidir. Belirteç kapsayıcınıza veya belirli bloblara atanabilir. Bkz. Belge Çevirisi işlemi için SAS belirteçleri oluşturma.
- Kaynak kapsayıcınızın veya blobunuzun okuma ve liste erişimi belirlemesi gerekir.
- Hedef kapsayıcınızın veya blobunuzun yazma ve liste erişimi belirlemesi gerekir.
- Sözlük blobunuzun okuma ve liste erişimi belirlemesi gerekir.
İpucu
- Bir işlemde birden çok dosya (blob) çeviriyorsanız, kapsayıcı düzeyinde SAS erişimini temsilci olarak belirleyin.
- Bir işlemde tek bir dosyayı (blob) çeviriyorsanız, blob düzeyinde SAS erişimini temsilci olarak belirleyin.
- SAS belirteçlerine alternatif olarak, kimlik doğrulaması için sistem tarafından atanan yönetilen kimliği kullanabilirsiniz.
HTTP istekleri
Post isteği aracılığıyla Translator hizmet uç noktanıza zaman uyumsuz bir toplu çeviri isteği gönderilir. Başarılı olursa POST yöntemi bir 202 Accepted
yanıt kodu döndürür ve hizmet bir toplu iş isteği oluşturur. Çevrilen belgeler hedef kapsayıcınızda listelenir.
Azure AI Translator Hizmeti istek sınırları hakkında ayrıntılı bilgi için bkz. Belge Çevirisi istek sınırları.
HTTP üst bilgileri
Her Belge Çevirisi API'sinin isteğine aşağıdaki üst bilgiler eklenir:
HTTP üst bilgisi | Açıklama |
---|---|
Ocp-Apim-Subscription-Key | Gerekli: Değer, Translator veya Azure AI hizmetleri kaynağınızın Azure anahtarıdır. |
İçerik Türü | Gerekli: Yükün içerik türünü belirtir. Kabul edilen değerler application/json veya charset=UTF-8 değerleridir. |
POST isteği gövdesi özellikleri
- POST isteği URL'si POST'tır
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches
. - POST isteği gövdesi adlı
inputs
bir JSON nesnesidir. inputs
nesnesi, kaynak vetargetURL
hedef dil çiftleriniz için hem hem desourceURL
kapsayıcı adreslerini içerir.- ve
prefix
suffix
, çeviri için kaynak yoldaki belgeleri filtrelemek için büyük/küçük harfe duyarlı dizelerdir. Alanprefix
genellikle çeviri için alt klasörlerin çizgisini belirlemek için kullanılır. Alansuffix
en sık dosya uzantıları için kullanılır. - Belge çevrilirken alan için
glossaries
bir değer (isteğe bağlı) uygulanır. targetUrl
Her hedef dil için benzersiz olmalıdır.
Not
Hedefte aynı ada sahip bir dosya zaten varsa, iş başarısız olur.
Kapsayıcıdaki tüm belgeleri çevirme
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "fr"
}
]
}
]
}
Kapsayıcıdaki belirli bir belgeyi çevirme
"storageType": "File"
belirtin.- Kimlik doğrulaması için sistem tarafından atanan yönetilen kimlik kullanmıyorsanız, belirli bir blob/belge için (kapsayıcı için değil) kaynak URL ve SAS belirteçleri oluşturduğunuzdan emin olun.
- HEDEF dosya adını hedef URL'nin bir parçası olarak belirttiğinizden emin olun; sas belirteci kapsayıcı için hala geçerli olsa da.
- Bu örnek istek, iki hedef dile çevrilmiş tek bir belge döndürür.
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es"
},
{
"targetUrl": "{targetSASUrl}",
"language": "de"
}
]
}
]
}
Özel sözlük kullanarak belgeleri çevirme
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es",
"glossaries": [
{
"glossaryUrl": "{glossaryUrl/en-es.xlf}",
"format": "xliff"
}
]
}
]
}
]
}
Belge Çevirisi isteklerini göndermek için kodu kullanma
Kodlama Platformunuzu ayarlama
- Yeni bir proje oluşturma.
- Program.cs değerini C# kod örneğiyle değiştirin.
- uç nokta, anahtar ve kapsayıcı URL'si değerlerinizi Program.cs ayarlayın.
- JSON verilerini işlemek için .NET CLI kullanarak Newtonsoft.Json paketi ekleyin.
- Programı proje dizininden çalıştırın.
Önemli
Kod örnekleri için Paylaşılan Erişim İmzası (SAS) URL'nizi belirtildiği yerde sabit kodlayacaksınız. İşiniz bittiğinde SAS URL'sini kodunuzdan kaldırmayı unutmayın ve bunu asla herkese açık olarak göndermeyin. Üretim için Azure Yönetilen Kimlik gibi kimlik bilgilerinizi depolamanın ve bunlara erişmenin güvenli bir yolunu kullanın. Daha fazla bilgi için bkz . Azure Depolama güvenliği.
İşleme bağlı olarak aşağıdaki alanları güncelleştirmeniz gerekebilir:
endpoint
basePath
key
sourceURL
targetURL
glossaryURL
id
(iş kimliği)
Değeri bulma id
- İşi
id
POSTstart-batch-translation
yöntemi yanıt Üst BilgiOperation-Location
URL'si değerinde bulabilirsiniz. parametresini/document/
izleyen alfasayısal dize, işlemin işidirid
:
Yanıt üst bilgisi | Yanıt URL'si |
---|---|
İşlem Konumu | {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec ?api-version={date} |
- Çeviri işlerinin ve işlerinin
id
listesini almak için get-translations-status isteği de kullanabilirsiniz.
Zaman uyumsuz toplu iş çevirisi başlatma
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "?api-version={date}";
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";
private static readonly string key = "{your-api-key}";
static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");
static async Task Main(string[] args)
{
using HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
StringContent content = new StringContent(json, Encoding.UTF8, "application/json");
request.Method = HttpMethod.Post;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
request.Content = content;
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
if (response.IsSuccessStatusCode)
{
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine();
Console.WriteLine($"Response Headers:");
Console.WriteLine(response.Headers);
}
else
Console.Write("Error");
}
}
}
Desteklenen belge biçimlerini alma
Desteklenen dosya biçimlerinin listesini alın. Başarılı olursa, bu yöntem bir 200 OK
yanıt kodu döndürür.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/formats";
static readonly string route = "?api-version={date}&type=document";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Çeviri işinin durumunu alma
Tek bir işin geçerli durumunu ve Belge Çevirisi isteğindeki tüm işlerin özetini alın. Başarılı olursa, bu yöntem bir 200 OK
yanıt kodu döndürür.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
}
Belirli bir belgenin durumunu alma
Kısa genel bakış
Belge Çevirisi isteğinde belirli bir belgenin durumunu alın. Başarılı olursa, bu yöntem bir 200 OK
yanıt kodu döndürür.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
İşi silme
Kısa genel bakış
şu anda işlenen veya kuyruğa alınmış işi iptal edin. Yalnızca çevirinin başlatılmadığı belgeler iptal edilir.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Ortak HTTP durum kodları
HTTP durum kodu | Açıklama | Olası neden |
---|---|---|
200 | Tamam | İstek başarılı oldu. |
400 | Hatalı İstek | Gerekli bir parametre eksik, boş veya null. Veya gerekli veya isteğe bağlı bir parametreye geçirilen değer geçersiz. Sık karşılaşılan bir sorun, çok uzun bir üst bilgidir. |
Kategori 401 | Yetkisiz | İstek yetkilendirilmedi. Anahtarınızın veya belirtecinizin geçerli ve doğru bölgede olduğundan emin olun. Aboneliğinizi Azure portalında yönetirken, Azure AI hizmetleri çok hizmetli kaynağını değil Translator tek hizmet kaynağını kullandığınızdan emin olun. |
429 | Çok Fazla İstek Var | Aboneliğiniz için izin verilen istek kotasını veya oranını aştınız. |
502 | Hatalı Ağ Geçidi | Ağ veya sunucu tarafı sorunu. Geçersiz üst bilgileri de gösterebilir. |