Kullanmaya başlayın Çevirisi ile Birlikte Çalışma
Bu makalede, Belge Çevirisi'nin HTTP ve REST API kullanmayı öğrenirsiniz. Belge Çevirisi, Azure Çeviri hizmetinin bulut tabanlı bir özelliğidir. Belge Çevirisi API'si, kaynak belge yapısını ve metin biçimlendirmesini korurken belgelerin tamamının çevirisini sağlar.
Önkoşullar
Not
- Genel olarak, bir Bilişsel Hizmet kaynağı Azure portal, çok hizmetli abonelik anahtarı veya tek hizmetli abonelik anahtarı oluşturma seçeneğiniz vardır. Ancak, Belge Çevirisi şu anda yalnızca Çeviri (tek hizmetli) kaynakta de desteklemektedir ve Bilişsel Hizmetler (çok hizmetli) kaynağına dahil değildir.
- Belge Çevirisi yalnızca S1 Standart Hizmet Planı 'da (Siz öde) veya D3 Toplu İndirim Planı'da kullanılabilir. Bkz. Bilişsel Hizmetler fiyatlandırması—Çeviri.
Çalışmaya başlama için şulere ihtiyacınız olacak:
Etkin bir Azure hesabı. Hesabınız yoksa ücretsiz bir hesap oluşturabilirsiniz.
Tek hizmetli Çeviri (çok hizmetli Bilişsel Hizmetler kaynağı değil).
Bir Azure blob depolama hesabı. Blob verilerinizi depolama hesabınız içinde depolamak ve düzenlemek için kapsayıcılar oluşturabilirsiniz.
Özel etki alanı adı ve abonelik anahtarı
Önemli
- Belge Çevirisi hizmetine yapılan tüm API istekleri için özel bir etki alanı uç noktası gerekir.
- Belge Çevirisi'ne HTTP istekleri yapmak için Azure portal Uç Nokta sayfasında veya genel çevirmen uç noktası olan — üzerinde bulunan uç
api.cognitive.microsofttranslator.comnoktayı kullanmazsınız.
Özel etki alanı uç noktası nedir?
Özel etki alanı uç noktası, kaynak adınız, ana bilgisayar adınız ve Çeviri biçimlendirilmiş bir URL'dir:
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0
Özel etki alanı adınızı bulma
KAYNAK ADI (özel etki alanı adı olarak da adlandırılan) parametresi, kaynak kaynağınızı oluşturulduğunda Ad alanına girdiğiniz Çeviri olur.
Abonelik anahtarınızı alma
Çeviri hizmetine yapılan istekler, erişimin kimlik doğrulama için salt okunur bir anahtar gerektirir.
- Yeni bir kaynak oluşturduysanız, dağıtımdan 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'ya seçin.
- Abonelik 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 aşağıdaki koda yapıştırabilirsiniz.
Azure blob depolama kapsayıcıları oluşturma
Kaynak ve hedef dosyalar için Azure blob depolama hesabı içinde kapsayıcılar oluşturmanız gerekir.
- Kaynak kapsayıcı. Bu kapsayıcı, dosyalarınızı çeviri için karşıya yüklediğiniz (gerekli) kapsayıcıdır.
- Hedef kapsayıcı. Bu kapsayıcı, çevrilmiş dosyalarınızın depolandığı (gerekli) kapsayıcıdır.
Not
Belge Çevirisi, hedef kapsayıcılarda (ayrı sözlük kapsayıcılarında değil) blob olarak sözlükleri destekler. Özel bir sözlük eklemek için hedef kapsayıcıya ekleyin ve istekle glossaryUrl birlikte ekleyin. Çeviri dili ç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, ve targetUrl isteğe glossaryUrl bağlı, sorgu dizesi olarak eklenen bir Paylaşılan Erişim İmzası (SAS) belirteci içermesi gerekir. 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 veya blob'uz için belirlenen okuma ve liste erişimine sahip olması gerekir.
- Hedef kapsayıcınız veya blob' un belirlenmiş yazma ve liste erişimine sahip olması gerekir.
- Sözlük blobu için belirlenmiş okuma ve liste erişimine sahip olması gerekir.
İpucu
- Bir işlemde birden çok dosya (blob) çevirisi ediyorsanız, kapsayıcı düzeyinde SAS erişimi için temsilci olarak seçin.
- Bir işlemde tek bir dosya (blob) çevirisi ediyorsanız, blob düzeyinde SAS erişimi için temsilci atabilirsiniz.
Belge Çevirisi: HTTP istekleri
Toplu Belge Çevirisi isteği, bir POST isteği Çeviri hizmet uç noktanıza gönderilir. Başarılı olursa POST yöntemi bir yanıt 202 Accepted kodu döndürür ve hizmet tarafından toplu iş isteği oluşturulur.
HTTP üst bilgileri
Aşağıdaki üst bilgiler her Bir Belge Çeviri API isteğine dahildir:
| HTTP üst bilgisi | Açıklama |
|---|---|
| Ocp-Apim-Subscription-Key | Gerekli: Değer, Çeviri veya Bilişsel Hizmetler kaynağınız için Azure abonelik 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. |
| İçerik Uzunluğu | Gerekli: İstek gövdesinin uzunluğu. |
POST isteği gövdesi özellikleri
- POST isteği URL'si POST'tir
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches - POST isteği gövdesi adlı bir JSON
inputsnesnesidir. - nesnesi,
inputskaynak ve hedef dilsourceURLtargetURLçiftleri için hem hem de kapsayıcı adreslerini içerir - Ve
prefixalanlarısuffix(isteğe bağlı) kapsayıcıda klasörler dahil olmak üzere belgeleri filtrelemek için kullanılır. - Belge
glossariesçevrilken alan için bir değer (isteğe bağlı) uygulanır. - Her
targetUrlhedef dil için benzersiz olmalıdır.
Not
Hedefte aynı adla bir dosya zaten varsa, iş başarısız olur.
Kapsayıcıda tüm belgeleri çevirme
{
"inputs": [
{
"source": {
"sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
},
"targets": [
{
"targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
"language": "fr"
}
]
}
]
}
Kapsayıcıda belirli bir belgeyi çevirme
- "storageType": "File" belirttiğinizden emin olun
- Belirli bir blob/belge & (kapsayıcı için değil) sas belirteci için kaynak URL'yi oluşturduğunuzdan emin olun
- HEDEF URL'nin bir parçası olarak hedef dosya adını belirttiğinizden emin olun, ancak SAS belirteci hala kapsayıcıya yöneliktir.
- Aşağıdaki örnek istek, iki hedef dile çevrilen tek bir belgeyi gösterir
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
},
"targets": [
{
"targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
"language": "es"
},
{
"targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
"language": "de"
}
]
}
]
}
Özel sözlük kullanarak belgeleri çevirme
{
"inputs": [
{
"source": {
"sourceUrl": "https://myblob.blob.core.windows.net/source",
"filter": {
"prefix": "myfolder/"
}
},
"targets": [
{
"targetUrl": "https://myblob.blob.core.windows.net/target",
"language": "es",
"glossaries": [
{
"glossaryUrl": "https:// myblob.blob.core.windows.net/glossary/en-es.xlf",
"format": "xliff"
}
]
}
]
}
]
}
Belge Çevirisi isteklerini göndermek için kod kullanma
Kodlama Platformunu ayarlama
- Yeni bir proje oluşturma.
- Program.cs'yi aşağıda gösterilen C# koduyla değiştirin.
- Program.cs'de uç noktanızı, abonelik anahtarınızı ve kapsayıcı URL'si değerlerinizi ayarlayın.
- JSON verilerini işlemeye .NET CLI kullanarak Newtonsoft.Json paketi ekleyin.
- Programı proje dizininden çalıştırın.
Önemli
Aşağıdaki kod örnekleri için anahtarınızı ve uç noktanızı belirtilen yere sabit olarak kodlayabilirsiniz; bitiren kodundan anahtarı kaldırmayı unutmayın ve hiçbir zaman herkese açık şekilde gönderin. Kimlik Azure Bilişsel Hizmetler güvenli bir şekilde depolama ve erişim yolları için bkz. güvenlik.
İşleme bağlı olarak aşağıdaki alanları güncelleştirmeniz gerekir:
endpointsubscriptionKeysourceURLtargetURLglossaryURLid(iş kimliği)
Değeri id bulma
- İş, POST yöntemi yanıt
idÜst Bilgisi URL'si değerindeOperation-Locationyer alır. URL'nin son parametresi, işlemidişidir:
| Yanıt üst bilgisi | Sonuç URL'si |
|---|---|
| Operation-Location | https://<-KAYNAĞıNIZIN ADI>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec |
- Belge Çevirisi işini almak için bir GET İşleri isteği de kullanabilirsiniz.
id
Belgeleri çevirme
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "/batches";
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";
private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";
static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\",\"filter\":{\"prefix\": \"Demo_1/\"} }, \"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(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
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");
}
}
}
}
Dosya biçimlerini al
Desteklenen dosya biçimlerinin listesini alın. Başarılı olursa, bu yöntem bir yanıt 200 OK kodu döndürür.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";
static readonly string route = "/documents/formats";
private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
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);
}
}
İş durumunu al
Bir Belge Çevirisi isteğinde tek bir işin geçerli durumunu ve tüm işlerin özetini elde edin. Başarılı olursa, bu yöntem bir yanıt 200 OK kodu döndürür.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";
static readonly string route = "/batches/{id}";
private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
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);
}
}
Belge durumunu al
Kısa genel bakış
Belge Çevirisi isteğinde belirli bir belgenin durumunu alma. Başarılı olursa, bu yöntem bir yanıt 200 OK kodu döndürür.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";
static readonly string route = "/{id}/document/{documentId}";
private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
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şlemeyi veya kuyruğa alınan işi iptal edin. Yalnızca çevirinin başlamamış olduğu belgeler iptal edilir.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";
static readonly string route = "/batches/{id}";
private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
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);
}
}
İçerik sınırları
Aşağıdaki tabloda, Belge Çevirisi'ne göndermek istediğiniz veri sınırları listelenmiştir.
| Öznitelik | Sınır |
|---|---|
| Belge boyutu | ≤ 40 MB |
| Toplam dosya sayısı. | ≤ 1000 |
| Toplu iş içinde toplam içerik boyutu | ≤ 250 MB |
| Toplu iş içinde hedef dil sayısı | ≤ 10 |
| Çeviri bellek dosyasının boyutu | ≤ 10 MB |
Belge Çevirisi, şifrelenmiş parolaya sahip veya içeriği kopyalamak için kısıtlı erişime sahip olanlar gibi güvenli belgeleri çevirmek için kullanılamaz.
Sorun giderme
Genel 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. Ya da gerekli veya isteğe bağlı bir parametreye geçirilen değer geçersiz. Yaygın bir sorun çok uzun bir üst bilgi. |
| 401 | Yetkisiz | İstek yetkili değil. Abonelik anahtarınızın veya belirtecinizin geçerli olduğundan ve doğru bölgede bulunduğundan emin olun. aboneliğinizi Azure portal yönetirken, lütfen bilişsel hizmetler çoklu hizmet kaynağı olmayan Çeviri tek hizmet kaynağını kullandığınızdan emin olun. |
| 429 | Çok fazla Istek | Aboneliğiniz için izin verilen kotayı veya isteklerin oranını aştınız. |
| 502 | Hatalı ağ geçidi | Ağ veya sunucu tarafı sorunu. Geçersiz üst bilgileri de gösterebilir. |