Aracılığıyla paylaş

REST API'lerini program aracılığıyla kullanma

  • Makale

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:

    1. Abonelik. Kullanılabilir Azure aboneliklerinizden birini seçin.

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

    3. 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.

    4. 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.

    5. Fiyatlandırma katmanı. Belge Çevirisi ücretsiz katmanda desteklenmez. Hizmeti denemek için Standart S1'i seçin.

    6. Gözden geçir + Oluştur’u seçin.

    7. Hizmet koşullarını gözden geçirin ve kaynağınızı dağıtmak için Oluştur'u seçin.

    8. 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.

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

  2. Sol rayda, Kaynak Yönetimi'nin altında Anahtarlar ve Uç Nokta'yı seçin.

  3. ve öğelerinizi keydocument 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.

  4. Belge key Çevirisi hizmetinde isteğinizin kimliğini doğrulamak için siz ve document translation endpoint kod örneklerine girin.

    Azure portalında anahtarınızı alma alanını gösteren ekran görüntüsü.

Anahtarınızı alın

Translator hizmetine yönelik istekler, erişimin kimliğini doğrulamak için salt okunur bir anahtar gerektirir.

  1. 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.
  2. Sol rayda, Kaynak Yönetimi'nin altında Anahtarlar ve Uç Nokta'yı seçin.
  3. 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 bunu kod örneğine yapıştırırsınız.

Azure portalında anahtarınızı alma alanının görüntüsü.

Azure Blob Depolama kapsayıcıları oluşturma

Kaynak ve hedef dosyalar için Azure Blob Depolama hesabınızda kapsayıcılaroluş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 belirlemesigerekir.

İ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ı inputsbir JSON nesnesidir.
  • inputs nesnesi, kaynak ve targetURL hedef dil çiftleriniz için hem hem de sourceURL kapsayıcı adreslerini içerir.
  • ve prefixsuffix , çeviri için kaynak yoldaki belgeleri filtrelemek için büyük/küçük harfe duyarlı dizelerdir. Alan prefix genellikle çeviri için alt klasörlerin çizgisini belirlemek için kullanılır. Alan suffix 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 POST start-batch-translation yöntemi yanıt Üst Bilgi Operation-Location URL'si değerinde bulabilirsiniz. parametresini /document/ izleyen alfasayısal dize, işlemin işidir id:
Yanıt üst bilgisi Yanıt URL'si
İşlem Konumu {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date}

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.

Daha fazla bilgi edinin

Sonraki adımlar

Özel Çeviri Aracı kullanarak özelleştirilmiş bir dil sistemi oluşturma