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

  1. 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.
  2. 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:

Ö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.com noktayı 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.

Kaynak oluşturma Azure portal, anlık ayrıntılar, ad alanı görüntüsü.

Abonelik anahtarınızı alma

Çeviri hizmetine yapılan istekler, erişimin kimlik doğrulama için salt okunur bir anahtar gerektirir.

  1. 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.
  2. Sol rayda, Kaynak Yönetimi'nin altında Anahtarlar ve Uç Nokta'ya seçin.
  3. Abonelik anahtarınızı kopyalayıp Microsoft Not Defteri gibi uygun bir konuma yapıştırın.
  4. Belge Çevirisi hizmetine isteğinizin kimliğini doğrulamak için aşağıdaki koda yapıştırabilirsiniz.

Azure portal'da abonelik anahtarınızı alma alanı görüntüsü.

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 inputs nesnesidir.
  • nesnesi, inputs kaynak ve hedef dil sourceURL targetURL çiftleri için hem hem de kapsayıcı adreslerini içerir
  • Ve prefix alanları 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 targetUrl hedef 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:

  • endpoint
  • subscriptionKey
  • sourceURL
  • targetURL
  • glossaryURL
  • id (iş kimliği)

Değeri id bulma

  • İş, POST yöntemi yanıt id Üst Bilgisi URL'si değerinde Operation-Location yer alır. URL'nin son parametresi, işlem id iş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.

Daha fazla bilgi edinin

Sonraki adımlar