Uruchamianie tłumaczenia wsadowego

Artykuł
09/26/2024

Funkcja referencyjna
: Azure AI Translator → interfejs API tłumaczenia
dokumentów Wersja: 2024-05-01
metoda HTTP: POST

Start Translation Użyj metody , aby wykonać asynchroniczne żądanie tłumaczenia wsadowego.
Metoda wymaga konta usługi Azure Blob Storage z kontenerami magazynu dla źródłowych i przetłumaczonych dokumentów.

Adres URL żądania

Ważne

Wszystkie żądania interfejsu API do funkcji tłumaczenia dokumentów wymagają niestandardowego punktu końcowego domeny znajdującego się na stronie przeglądu zasobu w witrynie Azure Portal.

  curl -i -X POST "{document-translation-endpoint}/translator/document/batches?api-version={date}"

Nagłówki żądań

Nagłówki żądań to:

Nagłówki	opis	Warunek
Ocp-Apim-Subscription-Key	Klucz interfejsu API usługi Translator z witryny Azure Portal.	Wymagane
Ocp-Apim-Subscription-Region	Region, w którym utworzono zasób.	Wymagane w przypadku korzystania z zasobu regionalnego (geograficznego), takiego jak Zachodnie stany USA. &punktor.
Typ zawartości	Typ zawartości ładunku. Zaakceptowana wartość to application/json lub charset=UTF-8.	Wymagane

BatchRequest (treść)

Każde żądanie może zawierać wiele dokumentów i musi zawierać kontener źródłowy i docelowy dla każdego dokumentu. Typy multimediów źródłowych: application/json, text/json, application/*+json.
Filtr prefiksu i sufiksu (jeśli podano) są używane do filtrowania folderów. Prefiks jest stosowany do ścieżki podrzędnej po nazwie kontenera.
Słowniki można uwzględnić w żądaniu. Jeśli słownik jest nieprawidłowy lub nie jest osiągalny podczas tłumaczenia, w stanie dokumentu jest wyświetlany błąd.
Jeśli plik o tej samej nazwie już istnieje w docelowym miejscu docelowym, zadanie zakończy się niepowodzeniem.
Element targetUrl dla każdego języka docelowego musi być unikatowy.


{
  "inputs": [
    {
      "source": {
        "sourceUrl": "https://myblob.blob.core.windows.net/Container/",
        "filter": {
          "prefix": "FolderA",
          "suffix": ".txt"
        },
        "language": "en",
        "storageSource": "AzureBlob"
      },
      "targets": [
        {
          "targetUrl": "https://myblob.blob.core.windows.net/TargetUrl/",
          "category": "general",
          "language": "fr",
          "glossaries": [
            {
              "glossaryUrl": "https://myblob.blob.core.windows.net/Container/myglossary.xlf",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
}

Dane wejściowe

Definicja dla wejściowego żądania tłumaczenia wsadowego.

Parametr klucza	Typ	Wymagania	Parametry żądania	opis
Wejścia	`array`	Prawda	• źródło (obiekt) • obiekty docelowe (tablica) • storageType (ciąg)	Dane źródła danych wejściowych.

inputs.source

Definicja danych źródłowych.

Parametr klucza	Typ	Wymagania	Parametry żądania	opis
inputs.source	`object`	Prawda	• sourceUrl (ciąg) • filtr (obiekt)• język (ciąg) • storageSource (ciąg)	Dane źródłowe dla dokumentów wejściowych.
inputs.source.sourceUrl	`string`	Prawda	•struna	Lokalizacja kontenera dla pliku źródłowego lub folderu.
inputs.source.filter	`object`	Fałsz	• prefiks (ciąg) • sufiks (ciąg)	Ciągi uwzględniające wielkość liter do filtrowania dokumentów w ścieżce źródłowej.
inputs.source.filter.prefix	`string`	Fałsz	•struna	Ciąg prefiksu z uwzględnieniem wielkości liter w celu filtrowania dokumentów w ścieżce źródłowej na potrzeby tłumaczenia. Często używane do wyznaczania podfolderów na potrzeby tłumaczenia. Przykład: "FolderA".
inputs.source.filter.sufiks	`string`	Fałsz	•struna	Ciąg sufiksu uwzględniający wielkość liter do filtrowania dokumentów w ścieżce źródłowej na potrzeby tłumaczenia. Najczęściej używane w przypadku rozszerzeń plików. Przykład: ".txt"
inputs.source.language	`string`	Fałsz	•struna	Kod języka dokumentów źródłowych. Jeśli nie zostanie określony, funkcja autowykrywania jest implementowana.
inputs.source.storageSource	`string`	Fałsz	•struna	Źródło magazynu dla danych wejściowych. Wartość domyślna to `AzureBlob`.

inputs.targets

Definicja danych docelowych i słowników.

Parametr klucza	Typ	Wymagania	Parametry żądania	opis
inputs.targets	`array`	Prawda	• targetUrl (ciąg) • kategoria (ciąg)• język (ciąg) • słowniki (tablica) • storageSource (ciąg)	Obiekty docelowe i dane słowników dla przetłumaczonych dokumentów.
inputs.targets.targetUrl	`string`	Prawda	•struna	Lokalizacja lokalizacji kontenera dla przetłumaczonych dokumentów.
inputs.targets.category	`string`	Fałsz	•struna	Klasyfikacja lub kategoria żądania tłumaczenia. Przykład: ogólne.
inputs.targets.language	`string`	Prawda	•struna	Kod języka docelowego. Przykład: "fr".
inputs.targets.glossaries	`array`	Fałsz	• słownikUrl (ciąg) • format (ciąg)• wersja (ciąg) • storageSource (ciąg)	Zobacz Tworzenie słowników i korzystanie z nich
inputs.targets.glossaries.glossaryUrl	`string`	True (jeśli używasz słowników)	•struna	Lokalizacja słownika. Rozszerzenie pliku służy do wyodrębniania formatowania, jeśli parametr formatu nie został podany. Jeśli para języków tłumaczenia nie jest obecna w słowniku, nie jest stosowana.
inputs.targets.glossaries.format	`string`	Fałsz	•struna	Określony format pliku słownika. Aby sprawdzić, czy format pliku jest obsługiwany, zobacz Uzyskiwanie obsługiwanych formatów słownika.
inputs.targets.glossaries.version	`string`	Fałsz	•struna	Wskaźnik wersji. Przykład: "2.0".
inputs.targets.glossaries.storageSource	`string`	Fałsz	•struna	Źródło magazynu dla słowników. Wartość domyślna to `_AzureBlob_`.
inputs.targets.storageSource	`string`	Fałsz	•struna	Źródło magazynu dla pliku targets.defaults do `_AzureBlob_`.

inputs.storageType

Definicja jednostki magazynu dla dokumentów wejściowych.

Parametr klucza	Typ	Wymagania	Parametry żądania	opis
inputs.storageType	`string`	Fałsz	•`Folder` • `File`	Typ magazynu ciągu źródłowego dokumentów wejściowych. Prawidłowe wartości to tylko "Folder" lub "Plik".

Opcje

Definicja dla wejściowego żądania tłumaczenia wsadowego.

Parametr klucza	Typ	Wymagania	Parametry żądania	opis
Opcje	`object`	Fałsz	Informacje źródłowe dotyczące dokumentów wejściowych.
options.experimental	`boolean`	Fałsz	•`true` • `false`	Wskazuje, czy żądanie zawiera funkcję eksperymentalną (jeśli dotyczy). Tylko wartości logiczne `true` lub `false` są prawidłowe.

Przykładowe żądanie

Poniżej przedstawiono przykłady żądań wsadowych.

Uwaga

W poniższych przykładach udzielono ograniczonego dostępu do zawartości kontenera usługi Azure Storage przy użyciu tokenu sygnatury dostępu współdzielonego (SAS).

Tłumaczenie wszystkich dokumentów w kontenerze

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Tłumaczenie wszystkich dokumentów w kontenerze stosujących słowniki

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?{SAS-token-query-string}",
                            "format": "xliff",
                            "version": "1.2"
                        }
                    ]

                }
            ]
        }
    ]
}

Tłumaczenie określonego folderu w kontenerze

Upewnij się, że w filtrze określono nazwę folderu (uwzględniana wielkość liter) jako prefiks.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Tłumaczenie określonego dokumentu w kontenerze

Określ wartość "storageType": File.
Utwórz źródłowy adres URL i token sygnatury dostępu współdzielonego dla określonego obiektu blob/dokumentu.
Określ docelową nazwę pliku jako część docelowego adresu URL — mimo że token SAS jest nadal przeznaczony dla kontenera.

To przykładowe żądanie przedstawia pojedynczy dokument przetłumaczony na dwa języki docelowe.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?{SAS-token-query-string}",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?{SAS-token-query-string}",
                    "language": "de"
                }
            ]
        }
    ]
}

Napiwek

Ta metoda zwraca parametr zadania id dla ciągów zapytania get-translation-status, get-documents-status, get-document-status i cancel-translation request.

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=2024-05-01
Możesz również użyć żądania get-translations-status , aby pobrać listę zadań tłumaczenia i ich ids.

Nagłówek odpowiedzi	Adres URL odpowiedzi
Lokalizacja operacji	{document-translation-endpoint}/translator/document/`9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec`?api-version=2024-05-01

Kody stanu odpowiedzi

Poniżej przedstawiono możliwe kody stanu HTTP zwracane przez żądanie.

Kod stanu	opis
202	Akceptowane. Pomyślne żądanie i utworzone żądanie wsadowe. Nagłówek Operation-Location wskazuje adres URL stanu z operacją ID.HeadersOperation-Location: ciąg
400	Nieprawidłowe żądanie. Nieprawidłowa prośba. Sprawdź parametry wejściowe.
401	Brak autoryzacji. Sprawdź poświadczenia.
429	Szybkość żądań jest zbyt wysoka.
500	Wewnętrzny błąd serwera.
503	Usługa jest obecnie niedostępna. Spróbuj ponownie później.
Inne kody stanu	• Zbyt wiele żądań. Serwer jest tymczasowy niedostępny

Odpowiedź błędna

Parametr klucza	Type	Opis
code	`string`	Wyliczenia zawierające kody błędów wysokiego poziomu. Możliwe wartości:</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Brak autoryzacji
wiadomość	`string`	Pobiera komunikat o błędzie wysokiego poziomu.
innerError	InnerTranslationError	Nowy format błędu wewnętrznego zgodny z wytycznymi interfejsu API usług AI platformy Azure. Ten komunikat o błędzie zawiera wymagane właściwości: ErrorCode, message i optional properties target, details(key value pair) i wewnętrzny błąd (można go zagnieżdżać).
wewnętrzny. Kod błędu	`string`	Pobiera ciąg błędu kodu.
innerError.message	`string`	Pobiera komunikat o błędzie wysokiego poziomu.
innerError.target	`string`	Pobiera źródło błędu. Na przykład byłoby `documents` to lub `document id` jeśli dokument jest nieprawidłowy.

Przykładowa odpowiedź na błąd

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "Service is temporary unavailable",
    "innerError": {
      "code": "ServiceTemporaryUnavailable",
      "message": "Service is currently unavailable.  Please try again later"
    }
  }
}

Następne kroki

Postępuj zgodnie z naszym przewodnikiem Szybki start, aby dowiedzieć się więcej na temat korzystania z tłumaczenia dokumentów i biblioteki klienta.

Wprowadzenie do tłumaczenia dokumentów

Udostępnij za pośrednictwem