Udostępnij za pośrednictwem

Programowe używanie interfejsów API REST

  • Artykuł

Tłumaczenie dokumentów to funkcja oparta na chmurze usługi Azure AI Translator . Interfejs API tłumaczenia dokumentów umożliwia asynchroniczne tłumaczenie całych dokumentów w obsługiwanych językach i różnych formatach plików przy zachowaniu struktury dokumentu źródłowego i formatowania tekstu. W tym przewodniku z instrukcjami dowiesz się, jak używać interfejsów API tłumaczenia dokumentów z wybranym językiem programowania i interfejsem API REST PROTOKOŁU HTTP.

Wymagania wstępne

Uwaga

Tłumaczenie dokumentów jest obsługiwane w standardowym planie usługowym S1 (płatność zgodnie z rzeczywistym użyciem) oraz w planach C2, C3, C4 i D3 ze zniżkami na ilość. ZobaczCennik usług Azure AI — Translator.

Aby rozpocząć pracę, potrzebne będą następujące elementy:

  • Aktywne konto platformy Azure. Jeśli go nie masz, możesz utworzyć bezpłatne konto

  • Konto Azure Blob Storage. Musisz również utworzyć kontenery na koncie usługi Azure Blob Storage dla plików źródłowych i docelowych:

    • Kontener źródłowy. Ten kontener służy do przekazywania plików do tłumaczenia (wymagane).
    • Kontener docelowy. W tym kontenerze przechowywane są przetłumaczone pliki (wymagane).

  • Zasób Tłumaczenia:

    Wypełnij pola Szczegóły projektu i instancji Translatora w następujący sposób:

    1. Subskrypcja. Wybierz jedną z dostępnych subskrypcji platformy Azure.

    2. Grupa zasobów. Możesz utworzyć nową grupę zasobów lub dodać swój zasób do istniejącej grupy zasobów, która ma ten sam cykl życia, uprawnienia i zasady.

    3. Region zasobów. Wybierz pozycję Globalny , chyba że Twoja firma lub aplikacja wymaga określonego regionu. Jeśli planujesz uwierzytelnianie przy użyciu tożsamości zarządzanej przypisanej przez system, wybierz region geograficzny, taki jak Zachodnie stany USA.

    4. Name. Wprowadź nazwę wybraną dla zasobu. Wybrana nazwa musi być unikatowa na platformie Azure.

      Uwaga

      Tłumaczenie dokumentów wymaga niestandardowego punktu końcowego domeny. Wartość, którą wprowadzasz w polu Nazwa, to niestandardowy parametr nazwy domeny dla twojego punktu końcowego.

    5. Poziom cenowy. Tłumaczenie dokumentów nie jest obsługiwane w warstwie Bezpłatna. Aby wypróbować usługę, wybierz pozycję Standardowa S1.

    6. Wybierz pozycję Przejrzyj i utwórz.

    7. Przejrzyj warunki usługi i wybierz pozycję Utwórz , aby wdrożyć zasób.

    8. Po pomyślnym wdrożeniu zasobu wybierz pozycję Przejdź do zasobu , aby pobrać klucz i punkt końcowy.

Pobierz swój klucz i niestandardowy punkt końcowy domeny

  • Żądania do usługi Translator wymagają klucza tylko do odczytu i niestandardowego punktu końcowego w celu uwierzytelnienia dostępu. Niestandardowy punkt końcowy domeny jest adresem URL sformatowanym przy użyciu nazwy zasobu, nazwy hosta i podkatalogów usługi Translator i jest dostępny w witrynie Azure Portal.

  1. Jeśli utworzono nowy zasób, po jego wdrożeniu wybierz pozycję Przejdź do zasobu. Jeśli masz istniejący zasób tłumaczenia dokumentów, przejdź bezpośrednio do strony zasobu.

  2. W lewej szynie w obszarze Zarządzanie zasobami wybierz pozycję Klucze i punkt końcowy.

  3. Skopiuj i wklej element key i document translation endpoint w dogodnej lokalizacji, na przykład w Notatniku Microsoft. Tylko jeden klucz jest wymagany do wykonania wywołania interfejsu API.

  4. Ty wstaw key i document translation endpoint do przykładów kodu, aby uwierzytelnić swoje żądanie w usłudze tłumaczenia dokumentów.

    Zrzut ekranu przedstawiający pole uzyskaj swój klucz w Azure portal.

Uzyskiwanie klucza

Żądania do usługi Translator wymagają klucza tylko do odczytu na potrzeby uwierzytelniania dostępu.

  1. Jeśli utworzono nowy zasób, po jego wdrożeniu wybierz pozycję Przejdź do zasobu. Jeśli masz istniejący zasób tłumaczenia dokumentów, przejdź bezpośrednio do strony zasobu.
  2. W lewej szynie w obszarze Zarządzanie zasobami wybierz pozycję Klucze i punkt końcowy.
  3. Skopiuj i wklej klucz w dogodnej lokalizacji, na przykład w Notatniku Microsoft.
  4. Wklej go do przykładowego kodu, aby uwierzytelnić żądanie w usłudze tłumaczenia dokumentów.

Obraz przedstawiający pole 'Pobierz klucz' w witrynie Azure Portal.

Tworzenie kontenerów usługi Azure Blob Storage

Musisz utworzyć kontenery na koncie usługi Azure Blob Storage dla plików źródłowych i docelowych.

  • Źródłowy kontener. Ten kontener służy do przekazywania plików do tłumaczenia (wymagane).
  • Kontener docelowy. W tym kontenerze przechowywane są przetłumaczone pliki (wymagane).

Uwaga

Tłumaczenie dokumentów obsługuje słowniki jako obiekty blob w kontenerach docelowych (nie są oddzielnymi kontenerami słownika). Jeśli chcesz dołączyć niestandardowy słownik, dodaj go do kontenera docelowego i dołącz go glossaryUrl do żądania. Jeśli para języków tłumaczenia nie jest obecna w słowniku, słownik nie jest stosowany. ZobaczTłumaczenie dokumentów przy użyciu niestandardowego słownika

Tworzenie tokenów dostępu sas na potrzeby tłumaczenia dokumentów

Element sourceUrl , targetUrl i opcjonalnie glossaryUrl musi zawierać token sygnatury dostępu współdzielonego (SAS) dołączony jako ciąg zapytania. Znacznik można przypisać do kontenera lub określonych obiektów blob. ZobaczCreate SAS tokens for Document Translation process (Tworzenie tokenów SAS na potrzeby procesu tłumaczenia dokumentów).

  • Źródłowy kontener lub obiekt blob musi przydzielić dostęp do odczytu i dostęp do listy.
  • Docelowy kontener lub obiekt blob musi mieć przypisany dostęp do zapisu i dostęp do listy.
  • Obiekt blob słownika musi określić dostęp do odczytu i do listy.

Napiwek

  • Jeśli tłumaczysz wiele plików (obiektów blob) w operacji, deleguj dostęp SAS na poziomie kontenera.
  • Jeśli tłumaczysz pojedynczy plik (obiekt blob) w operacji, deleguj dostęp sas na poziomie obiektu blob.
  • Alternatywą dla tokenów SAS jest użycie tożsamości zarządzanej przypisanej przez system do uwierzytelniania.

Żądania HTTP

Żądanie wsadowego tłumaczenia asynchronicznego jest wysyłane do punktu końcowego usługi Translator za pomocą żądania POST. Jeśli operacja zakończy się sukcesem, metoda POST zwraca odpowiedź kodu 202 Accepted, a usługa tworzy żądanie wsadowe. Przetłumaczone dokumenty są wyświetlane w kontenerze docelowym.

Aby uzyskać szczegółowe informacje dotyczące limitów żądań usługi Azure AI Translator, zobacz Limity żądań tłumaczenia dokumentów.

Nagłówki HTTP

Następujące nagłówki są dołączane do każdego żądania interfejsu API tłumaczenia dokumentów:

Nagłówek HTTP opis
Ocp-Apim-Subscription-Key Wymagane: wartość jest kluczem platformy Azure dla zasobu usług Translator lub Azure AI.
Typ zawartości Wymagane: określa typ zawartości ładunku. Akceptowane wartości to application/json lub charset=UTF-8.

Właściwości treści żądania POST

  • Adres URL żądania POST to POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
  • Treść żądania POST jest obiektem JSON o nazwie inputs.
  • Obiekt inputs zawiera zarówno adresy kontenerów, jak sourceURL i targetURL dla par językowych źródłowych i docelowych.
  • Ciągi prefix i suffix, uwzględniające wielkość liter, służą do filtrowania dokumentów w ścieżce źródłowej na potrzeby tłumaczenia. Pole prefix jest często używane do delineowania podfolderów na potrzeby tłumaczenia. Pole suffix jest najczęściej używane w przypadku rozszerzeń plików.
  • Wartość glossaries pola (opcjonalnie) jest stosowana podczas tłumaczenia dokumentu.
  • Wartość targetUrl dla każdego języka docelowego musi być unikatowa.

Uwaga

Jeśli plik o tej samej nazwie już istnieje w miejscu docelowym, zadanie zakończy się niepowodzeniem.

Tłumaczenie wszystkich dokumentów w kontenerze

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Tłumaczenie określonego dokumentu w kontenerze

  • Podaj wartość "storageType": "File".
  • Jeśli nie używasz zarządzanej przez system tożsamości do uwierzytelniania, upewnij się, że utworzyłeś źródłowy adres URL i tokeny SAS dla określonego obiektu blob/dokumentu (a nie dla kontenera).
  • Upewnij się, że nazwa pliku docelowego została określona jako część docelowego adresu URL — mimo że token SAS jest nadal przeznaczony dla kontenera.
  • To przykładowe żądanie zwraca pojedynczy dokument przetłumaczony na dwa języki docelowe.
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "{sourceSASUrl}"
            },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es"
                },
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "de"
                }
            ]
        }
    ]
}

Tłumaczenie dokumentów przy użyciu niestandardowego słownika

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "{sourceSASUrl}"
             },
            "targets": [
                {
                    "targetUrl": "{targetSASUrl}",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "{glossaryUrl/en-es.xlf}",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

🆕 Tłumaczenie tekstu osadzonego na obrazach w dokumentach

Uwaga

  • Ta funkcja jest opcjonalna i musi być włączona dla każdego żądania tłumaczenia.
  • Włączenie tej funkcji spowoduje naliczenie dodatkowych kosztów na podstawie użycia. Aby uzyskać więcej informacji, zobaczCennik usługi Azure AI Vision
  • Ta funkcja jest obecnie dostępna tylko w interfejsie API wsadowego tłumaczenia dokumentów.
  • Obsługiwany format pliku jest .docx tylko.
  • Do korzystania z tej funkcji jest wymagany zasób usługi Azure AI Services (nie autonomiczny zasób usługi Translator).

Konfiguracja żądania

  • Użyj parametru translateTextWithinImage opcjonalnie w polu options

    • Typ danych: Boolean (true lub false)
    • Domyślne ustawienie wartości logicznej to false. Ustaw opcję na true, aby włączyć tłumaczenie tekstu obrazu.

  • Szczegóły odpowiedzi. Po włączeniu funkcji dodano informacje o przetwarzaniu obrazów wraz z odpowiedzią:

    • totalImageScansSucceeded. Liczba pomyślnie przetłumaczonych skanowań obrazów.

    • totalImageScansFailed. Liczba skanowań obrazów, które zakończyły się niepowodzeniem.

Przesyłanie żądań tłumaczenia dokumentów przy użyciu kodu

Konfigurowanie platformy kodowania

Ważne

W przypadku przykładów kodu należy wpisać na stałe swój adres URL sygnatury dostępu współdzielonego (SAS) w podanych miejscach. Pamiętaj, aby usunąć adres URL SAS ze swojego kodu po zakończeniu pracy i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego użyj bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń, takich jak tożsamość zarządzana platformy Azure. Aby uzyskać więcej informacji, zobacz Zabezpieczenia usługi Azure Storage.

W zależności od operacji może być konieczne zaktualizowanie następujących pól:

  • endpoint
  • basePath
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (identyfikator zadania)

Lokalizowanie id wartości

  • Zadanie id można znaleźć w wartości adresu URL nagłówka start-batch-translation odpowiedzi metody POSTOperation-Location. Ciąg alfanumeryczny po parametrze /document/ jest zadaniem idoperacji :
Nagłówek odpowiedzi Adres URL odpowiedzi
Lokalizacja operacji {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date}

Rozpocznij asynchroniczne tłumaczenie wsadowe


    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");

            }

        }

    }

Pobieranie obsługiwanych formatów dokumentów

Pobierz listę obsługiwanych formatów plików. Jeśli ta metoda powiedzie się, zwraca 200 OK kod odpowiedzi.


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);
            }
}

Pobieranie stanu zadania tłumaczenia

Pobierz bieżący stan pojedynczego zadania i podsumowanie wszystkich zadań w żądaniu tłumaczenia dokumentów. Jeśli ta metoda powiedzie się, zwraca 200 OK kod odpowiedzi.


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);
            }
    }
}

Uzyskiwanie stanu określonego dokumentu

Krótkie omówienie

Pobierz stan określonego dokumentu w żądaniu tłumaczenia dokumentów. Jeśli ta metoda powiedzie się, zwraca 200 OK kod odpowiedzi.


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);
            }
}

Usuwanie zadania

Krótkie omówienie

Anuluj zadanie, które jest obecnie przetwarzane lub znajduje się w kolejce. Anulowane są tylko dokumenty, dla których tłumaczenie nie zostało uruchomione.


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);
            }
}

Typowe kody stanu HTTP

Kod stanu HTTP opis Możliwe przyczyny
200 OK Żądanie zakończyło się pomyślnie.
400 Nieprawidłowe żądanie Brak wymaganego parametru, pusty lub null. Lub wartość przekazana do wymaganego lub opcjonalnego parametru jest nieprawidłowa. Typowym problemem jest nagłówek, który jest za długi.
401 Brak autoryzacji Żądanie nie jest autoryzowane. Upewnij się, że klucz lub token jest prawidłowy i w poprawnym regionie.
429 Zbyt wiele żądań Przekroczono limit lub szybkość żądań dozwolonych dla Twojej subskrypcji.
502 Nieprawidłowa brama Problem po stronie sieci lub serwera. Może również wskazywać nieprawidłowe nagłówki.

Dowiedz się więcej

Następne kroki

Tworzenie niestandardowego systemu językowego przy użyciu usługi Custom Translator