Rozpocznij tłumaczenie

Artykuł
02/12/2024

Usługa referencyjna
: Wersja interfejsu API tłumaczenia
dokumentów sztucznej inteligencji platformy Azure: wersja 1.1

Użyj tego interfejsu API, aby uruchomić żądanie tłumaczenia z usługą tłumaczenia dokumentów. Każde żądanie może zawierać wiele dokumentów i musi zawierać kontener źródłowy i docelowy dla każdego dokumentu.

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/pamięć tłumaczenia można uwzględnić w żądaniu i zastosować przez usługę podczas tłumaczenia dokumentu.

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 miejscu docelowym, zadanie zakończy się niepowodzeniem. Element targetUrl dla każdego języka docelowego musi być unikatowy.

Adres URL żądania

Wyślij żądanie POST do:

POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches

Dowiedz się, jak znaleźć niestandardową nazwę domeny.

Ważne

Wszystkie żądania interfejsu API do usługi tłumaczenia dokumentów wymagają niestandardowego punktu końcowego domeny.
Nie można użyć punktu końcowego znajdującego się na stronie kluczy zasobów i punktu końcowego witryny Azure Portal, ani globalnego punktu końcowego translatora —api.cognitive.microsofttranslator.com w celu wysłania żądań HTTP do tłumaczenia dokumentów.

Nagłówki żądań

Nagłówki żądań to:

Nagłówki	opis
Ocp-Apim-Subscription-Key	Wymagany nagłówek żądania

BatchRequest (treść)

Definicja dla wejściowego żądania tłumaczenia wsadowego. 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.


{
  "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.tsv",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
  "options": {
    "experimental": true
  }
}

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	•Ciąg	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	•Ciąg	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	•Ciąg	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	•Ciąg	Kod języka dokumentów źródłowych. Jeśli nie zostanie określony, funkcja autowykrywania jest implementowana.
inputs.source.storageSource	`string`	Fałsz	•Ciąg	Ź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	•Ciąg	Lokalizacja lokalizacji kontenera dla przetłumaczonych dokumentów.
inputs.targets.category	`string`	Fałsz	•Ciąg	Klasyfikacja lub kategoria żądania tłumaczenia. Przykład: ogólne.
inputs.targets.language	`string`	Prawda	•Ciąg	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)	ZobaczTworzenie słowników i korzystanie z nich
inputs.targets.glossaries.glossaryUrl	`string`	True (jeśli używasz słowników)	•Ciąg	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	•Ciąg	Określony format pliku słownika. Aby sprawdzić, czy format pliku jest obsługiwany, zobaczUzyskiwanie obsługiwanych formatów słownika.
inputs.targets.glossaries.version	`string`	Fałsz	•Ciąg	Wskaźnik wersji. Przykład: "2.0".
inputs.targets.glossaries.storageSource	`string`	Fałsz	•Ciąg	Źródło magazynu dla słowników. Wartość domyślna to `_AzureBlob_`.
inputs.targets.storageSource	`string`	Fałsz	•Ciąg	Źródło magazynu dla obiektów docelowych. Wartość domyślna to `_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?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"
                }
            ]
        }
    ]
}

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

{
    "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",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=BsciG3NWoOoRjOYesTaUmxlXzyjsX4AgVkt2AsxJ9to%3D",
                            "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?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "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"
                }
            ]
        }
    ]
}

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?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"
                }
            ]
        }
    ]
}

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łowe żądanie. 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 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: 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. Errorcode	`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łady

Przykład pomyślnej odpowiedzi

Następujące informacje są zwracane w pomyślnej odpowiedzi.

Identyfikator zadania można znaleźć w wartości adres URL nagłówka operacji-lokalizacji odpowiedzi metody POST. Ostatnim parametrem adresu URL jest identyfikator zadania operacji (ciąg następujący: "/operation/").

Operation-Location: https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55

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

Share via