Zahájení překladu

  • Článek

Referenční
služba: Verze rozhraní API pro překlad
dokumentů Azure AI: verze 1.1

Pomocí tohoto rozhraní API můžete spustit žádost o překlad ve službě Překlad dokumentů. Každý požadavek může obsahovat více dokumentů a musí obsahovat zdrojový a cílový kontejner pro každý dokument.

Filtr předpony a přípony (pokud je zadán) slouží k filtrování složek. Předpona se použije na dílčí cestu za názvem kontejneru.

Glosáře nebo paměť překladu mohou být zahrnuty do požadavku a použity službou při překladu dokumentu.

Pokud je glosář během překladu neplatný nebo nedostupný, zobrazí se ve stavu dokumentu chyba. Pokud v cíli již existuje soubor se stejným názvem, úloha selže. Hodnota targetUrl pro každý cílový jazyk musí být jedinečná.

Adresa URL požadavku

Odešlete požadavek POST do:

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

Zjistěte, jak najít vlastní název domény.

Důležité

  • Všechny požadavky rozhraní API na službu překladu dokumentů vyžadují vlastní koncový bod domény.
  • Koncový bod, který najdete na stránce klíčů prostředků a koncovém bodu webu Azure Portal, ani globální koncový bodapi.cognitive.microsofttranslator.com překladače – nemůžete použít k provádění požadavků HTTP na překlad dokumentů.

Záhlaví žádosti

Hlavičky požadavku jsou:

Hlavičky Popis
Ocp-Apim-Subscription-Key Požadovaná hlavička požadavku

BatchRequest (tělo)

Definice vstupní dávkového překladu. Každý požadavek může obsahovat více dokumentů a musí obsahovat zdrojový a cílový kontejner pro každý dokument. Typy zdrojových médií: application/json, application/*+jsontext/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
  }
}

Vstupy

Definice vstupní dávkového překladu.

Klíčový parametr Typ Požaduje se Parametry požadavku Popis
Vstupy array True • zdroj (objekt)

• cíle (pole)

• storageType (řetězec)		 Vstupní zdrojová data

inputs.source

Definice zdrojových dat

Klíčový parametr Typ Požaduje se Parametry požadavku Popis
inputs.source object True • sourceUrl (string)

• filtr (objekt)

• jazyk (řetězec)

• storageSource (řetězec)		 Zdrojová data pro vstupní dokumenty
inputs.source.sourceUrl string True •Řetězec Umístění kontejneru pro zdrojový soubor nebo složku
inputs.source.filter object False • předpona (řetězec)

• přípona (řetězec)		 Řetězce citlivé na malá a velká písmena pro filtrování dokumentů ve zdrojové cestě.
inputs.source.filter.prefix string False •Řetězec Řetězec předpony rozlišující malá a velká písmena pro filtrování dokumentů ve zdrojové cestě pro překlad. Často se používá k určení podsložek pro překlad. Příklad: FolderA.
inputs.source.filter.suffix string False •Řetězec Řetězec přípony rozlišující malá a velká písmena pro filtrování dokumentů ve zdrojové cestě pro překlad. Nejčastěji se používá pro přípony souborů. Příklad: ".txt"
inputs.source.language string False •Řetězec Kód jazyka pro zdrojové dokumenty. Pokud není zadáno, je implementováno automatické rozpoznávání.
inputs.source.storageSource string False •Řetězec Zdroj úložiště pro vstupy Výchozí hodnota AzureBlobje .

vstupy.targets

Definice pro data cílových a glosářů

Klíčový parametr Typ Požaduje se Parametry požadavku Popis
vstupy.targets array True • targetUrl (řetězec)

• kategorie (řetězec)

• jazyk (řetězec)

• glosáře (pole)

• storageSource (řetězec)		 Cíle a data glosářů pro přeložené dokumenty
inputs.targets.targetUrl string True •Řetězec Umístění umístění kontejneru pro přeložené dokumenty
inputs.targets.category string False •Řetězec Klasifikace nebo kategorie žádosti o překlad Příklad: obecné.
inputs.targets.language string True •Řetězec Kód cílového jazyka. Příklad: "fr".
inputs.targets.glossaries array False • glosářUrl (řetězec)

• formát (řetězec)

• verze (řetězec)

• storageSource (řetězec)		 VizVytváření a používání glosářů
inputs.targets.glossaries.glossaryUrl string True (pokud používáte glosáře) •Řetězec Umístění glosáře. Přípona souboru se používá k extrahování formátování, pokud není zadaný parametr formátu. Pokud pár jazyka překladu není v glosáři, nepoužije se.
inputs.targets.glossaries.format string False •Řetězec Zadaný formát souboru pro glosář. Pokud chcete zkontrolovat, jestli je formát souboru podporovaný, přečtěte si článekZískání podporovaných formátů glosáře.
inputs.targets.glossaries.version string False •Řetězec Indikátor verze Příklad: 2.0.
inputs.targets.glossaries.storageSource string False •Řetězec Zdroj úložiště pro glosáře Výchozí hodnota _AzureBlob_je .
inputs.targets.storageSource string False •Řetězec Zdroj úložiště pro cíle Výchozí hodnota _AzureBlob_je .

inputs.storageType

Definice entity úložiště pro vstupní dokumenty

Klíčový parametr Typ Požaduje se Parametry požadavku Popis
inputs.storageType string False •Folder

• File		 Typ úložiště zdrojového řetězce vstupních dokumentů Platné hodnoty jsou pouze "Složka" nebo "Soubor".

Možnosti

Definice vstupní dávkového překladu.

Klíčový parametr Typ Požaduje se Parametry požadavku Popis
Možnosti object False Informace o zdroji pro vstupní dokumenty
options.experimental boolean False •true

• false		 Určuje, jestli požadavek obsahuje experimentální funkci (pokud je k dispozici). Pouze logické true hodnoty nebo false jsou platné hodnoty.

Příklad požadavku

Tady jsou příklady dávkových požadavků.

Poznámka:

V následujících příkladech byl k obsahu kontejneru Azure Storage udělen omezený přístup pomocí tokenu sdíleného přístupového podpisu (SAS).

Překlad všech dokumentů v kontejneru

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

Překlad všech dokumentů v kontejneru s použitím glosářů

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

                }
            ]
        }
    ]
}

Překlad konkrétní složky v kontejneru

Ujistěte se, že jako předponu ve filtru zadáte název složky (rozlišují se malá a velká písmena).

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

Překlad konkrétního dokumentu v kontejneru

  • Zadejte "storageType": File.
  • Vytvořte zdrojový token URL a SAS pro konkrétní objekt blob nebo dokument.
  • Jako součást cílové adresy URL zadejte cílový název souboru, i když token SAS je stále pro kontejner.

Tento ukázkový požadavek ukazuje jeden dokument přeložený do dvou cílových jazyků.

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

Stavové kódy odpovědí

Níže jsou uvedené možné stavové kódy HTTP, které požadavek vrátí.

Kód stavu Popis
202 Přijata. Úspěšný požadavek a vytvořený dávkový požadavek Hlavička Operation-Location označuje stavovou adresu URL s id operace ID.HeadersOperation-Location: řetězec
400 Chybný požadavek. Neplatný požadavek Zkontrolujte vstupní parametry.
401 Neautorizováno Zkontrolujte přihlašovací údaje.
429 Frekvence požadavků je příliš vysoká.
500 Vnitřní chyba serveru.
503 Služba je momentálně nedostupná. Zkuste to později.
Další stavové kódy • Příliš mnoho požadavků
• Server je dočasný nedostupný

Chybná odpověď

Klíčový parametr Typ Popis
code string Výčty obsahující kódy chyb vysoké úrovně. Možné hodnoty:
  • InternalServerError
  • InvalidArgument
  • Neplatný dotaz
  • RequestRateTooHigh
  • ResourceNotFound
  • ServiceUnavailable
  • Neautorizováno
zpráva string Získá chybovou zprávu vysoké úrovně.
innerError InnerTranslationError Nový formát vnitřní chyby, který odpovídá pokynům rozhraní API služeb Azure AI Tato chybová zpráva obsahuje požadované vlastnosti: ErrorCode, message a optional properties target, details(key value pair) a inner error(může být vnořena).
Vnitřní. Errorcode string Získá řetězec chyby kódu.
innerError.message string Získá chybovou zprávu vysoké úrovně.
innerError.target string Získá zdroj chyby. Může to být documents například nebo document id pokud je dokument neplatný.

Příklady

Příklad úspěšné odpovědi

Následující informace se vrátí v úspěšné odpovědi.

ID úlohy najdete v hodnotě adresy URL hlavičky operace operace-umístění metody POST. Posledním parametrem adresy URL je ID úlohy operace (řetězec následující "/operation/").

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

Příklad odpovědi na chybu

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

Další kroky

Další informace o použití překladu dokumentů a klientské knihovny najdete v našem rychlém startu.

Začínáme s překladem dokumentů