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 planach usług standardowych S1 (płatność zgodnie z rzeczywistym użyciem) i C2, C3, C4 i D3 w planach rabatów zbiorczych. Zobacz Cennik 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 usługi 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 usługi Translator:

    Wypełnij pola Szczegóły projektu i wystąpienia usługi Translator 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ć zasób do istniejącej grupy zasobów, która współudzieli 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ść wprowadzona w polu Nazwa będzie parametrem niestandardowej nazwy domeny dla punktu końcowego.

    5. Warstwa cenowa. 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.

Pobieranie klucza i niestandardowego punktu końcowego 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 key i document translation endpoint do przykładów kodu, aby uwierzytelnić żądanie w usłudze tłumaczenia dokumentów.

    Zrzut ekranu przedstawiający pole pobierz klucz w witrynie 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.

  • 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).

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 element glossaryUrl z żądaniem. Jeśli para języków tłumaczenia nie jest obecna w słowniku, nie zostanie zastosowana. Zobacz Tł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. Token można przypisać do kontenera lub określonych obiektów blob. Zobacz Create 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 wyznaczyć dostęp do odczytu i listy.
  • Docelowy kontener lub obiekt blob musi wyznaczyć dostęp do zapisu i listy.
  • Obiekt blob słownika musi wyznaczyć dostęp do odczytu i 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 asynchronicznego tłumaczenia wsadowego jest przesyłane do punktu końcowego usługi Translator za pośrednictwem żądania POST. Jeśli operacja powiedzie się, metoda POST zwraca 202 Accepted kod odpowiedzi, 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 z suffix uwzględnieniem wielkości liter są uwzględniane w celu 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 tożsamości zarządzanej przypisanej przez system do uwierzytelniania, upewnij się, że utworzono źródłowe tokeny URL i SAS dla określonego obiektu blob/dokumentu (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, zobacz Cennik usługi Azure AI Vision
  • Ta funkcja jest obecnie dostępna tylko w interfejsie API tłumaczenia dokumentów wsadowych.
  • 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 opcjonalnego translateTextWithinImage parametru options w polu

    • Typ danych: wartość logiczna (true lub false)
    • Domyślne ustawienie wartości logicznej to false. Ustaw opcję , aby true 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 zakodowyć adres URL sygnatury dostępu współdzielonego (SAS), w którym wskazano. Pamiętaj, aby usunąć adres URL sygnatury dostępu współdzielonego z kodu po zakończeniu 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 Operation-Location odpowiedzi metody POSTstart-batch-translation. 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}

Rozpoczynanie asynchronicznego tłumaczenia wsadowego


    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 obecnie przetwarzanie lub zadanie 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 przydziału lub szybkość żądań dozwolonych dla 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