Iniciar tradução

Artigo
02/12/2024

Referência
Serviço: Tradução de documentos da IA do Azure
Versão da API: v1.1

Use essa API para iniciar uma solicitação de tradução com o serviço de tradução de documento. Cada solicitação pode conter vários documentos e deve incluir um contêiner de origem e de destino para cada documento.

O filtro de prefixo e de sufixo (se fornecidos) são usados para filtrar pastas. O prefixo é aplicado ao subcaminho após o nome do contêiner.

Os glossários/memória de tradução podem ser incluídos na solicitação e aplicados pelo serviço quando o documento for traduzido.

Se o glossário for inválido ou inacessível durante a tradução, um erro será indicado no status do documento. Se um arquivo com o mesmo nome já existir no destino, o trabalho falhará. A targetUrl para cada idioma de destino deve ser exclusivo.

URL da solicitação

Envie uma solicitação POST para:

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

Saiba como localizar seu nome de domínio personalizado.

Importante

Todas as solicitações de API ao serviço de Tradução de Documento exigem um ponto de extremidade de domínio personalizado.
Não é possível usar o ponto de extremidade encontrado na página Chaves e ponto de extremidade de recursos do portal do Azure nem o ponto de extremidade do tradutor global (api.cognitive.microsofttranslator.com) para fazer solicitações HTTP para a Tradução de Documento.

Cabeçalhos da solicitação

Os cabeçalhos de solicitação são:

Cabeçalhos	Descrição
Ocp-Apim-Subscription-Key	Cabeçalho de solicitação necessário

BatchRequest (corpo)

Definição para a solicitação de tradução de lote de entrada. Cada solicitação pode conter vários documentos e deve incluir um contêiner de origem e de destino para cada documento. Tipos de mídia de origem: 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
  }
}

Entradas

Definição para a solicitação de tradução de lote de entrada.

Parâmetro de chave	Tipo	Obrigatório	Parâmetros da solicitação	Descrição
Entradas	`array`	Verdadeiro	• source (objeto) • targets (matriz) • storageType (cadeia de caracteres)	Dados de origem de entrada.

inputs.source

Definição para os dados de origem.

Parâmetro de chave	Tipo	Obrigatório	Parâmetros da solicitação	Descrição
inputs.source	`object`	Verdadeiro	• sourceUrl (cadeia de caracteres) • filter (objeto) • language (cadeia de caracteres) • storageSource (cadeia de caracteres)	Dados de origem para documentos de entrada.
inputs.source.sourceUrl	`string`	Verdadeiro	•corda	Local do contêiner para o arquivo ou pasta de origem.
inputs.source.filter	`object`	Falso	• prefix (cadeia de caracteres) • suffix (cadeia de caracteres)	Cadeias de caracteres que diferenciam maiúsculas de minúsculas para filtrar documentos no caminho de origem.
inputs.source.filter.prefix	`string`	Falso	•corda	Uma cadeia de caracteres de prefixo que diferencia maiúsculas de minúsculas para filtrar documentos no caminho de origem para tradução. Frequentemente usado para designar subpastas para tradução. Exemplo: "PastaA".
inputs.source.filter.suffix	`string`	Falso	•corda	Uma cadeia de caracteres de sufixo que diferencia maiúsculas de minúsculas para filtrar documentos no caminho de origem para tradução. É mais frequentemente usado para extensões de arquivo. Examplo: ".txt"
inputs.source.language	`string`	Falso	•corda	O código de idioma para os documentos de origem. Se não for especificado, a detecção automática será implementada.
inputs.source.storageSource	`string`	Falso	•corda	Fonte de armazenamento para entradas. Assume o padrão de `AzureBlob`.

inputs.targets

Definição para dados de destino e de glossários.

Parâmetro de chave	Tipo	Obrigatório	Parâmetros da solicitação	Descrição
inputs.targets	`array`	Verdadeiro	• targetUrl (cadeia de caracteres) • category (cadeia de caracteres) • language (cadeia de caracteres) • glossaries (matriz) • storageSource (cadeia de caracteres)	Dados do destino e de glossários para documentos traduzidos.
inputs.targets.targetUrl	`string`	Verdadeiro	•corda	Local da localização do contêiner para documentos traduzidos.
inputs.targets.category	`string`	Falso	•corda	Classificação ou categoria para a solicitação de tradução. Exemplo: geral.
inputs.targets.language	`string`	Verdadeiro	•corda	Código do idioma de destino. Exemplo: "fr".
inputs.targets.glossaries	`array`	Falso	• glossaryUrl (cadeia de caracteres) • format (cadeia de caracteres) • version (cadeia de caracteres) • storageSource (cadeia de caracteres)	ConsulteCriar e usar glossários
inputs.targets.glossaries.glossaryUrl	`string`	True (se estiver usando glossários)	•corda	Local do glossário. A extensão de arquivo é usada para extrair a formatação se o parâmetro de formato não for fornecido. Se o par de idiomas de tradução não estiver presente no glossário, ele não será aplicado.
inputs.targets.glossaries.format	`string`	Falso	•corda	Formato de arquivo especificado para glossário. Para verificar se o formato de arquivo é suportado, confiraObter os formatos de glossário suportados.
inputs.targets.glossaries.version	`string`	Falso	•corda	Indicador de versão. Exemplo: "2.0".
inputs.targets.glossaries.storageSource	`string`	Falso	•corda	Fonte de armazenamento para glossários. Assume o padrão de `_AzureBlob_`.
inputs.targets.storageSource	`string`	Falso	•corda	Origem de armazenamento para destinos. O padrão é `_AzureBlob_`.

inputs.storageType

Definição da entidade de armazenamento para documentos de entrada.

Parâmetro de chave	Tipo	Obrigatório	Parâmetros da solicitação	Descrição
inputs.storageType	`string`	Falso	••`Folder` `File`	Tipo de armazenamento da cadeia de caracteres de origem dos documentos de entrada. Somente "Pasta" ou "Arquivo" são valores válidos.

Opções

Definição para a solicitação de tradução de lote de entrada.

Parâmetro de chave	Tipo	Obrigatório	Parâmetros da solicitação	Descrição
options	`object`	Falso	Informações de origem para documentos de entrada.
options.experimental	`boolean`	Falso	••`true` `false`	Indica se a solicitação inclui um recurso experimental (se aplicável). Somente os boolianos `true` ou `false` são valores válidos.

Solicitação de exemplo

Veja os seguintes exemplos de solicitações de lote.

Observação

Nos exemplos a seguir, foi concedido acesso limitado ao conteúdo de um contêiner de Armazenamento do Microsoft Azure usando um token SAS (assinatura de acesso compartilhado).

Traduzir todos os documentos em um contêiner

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

Traduzir todos os documentos em um contêiner aplicando glossários

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

                }
            ]
        }
    ]
}

Traduzir pasta específica em um contêiner

Certifique-se de especificar o nome da pasta (diferencia maiúsculas de minúsculas) como prefixo no filtro.

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

Traduzir documento específico em um contêiner

Especifique "storageType": File.
Crie URL de origem & token SAS para o blob/documento específico.
Especificar o nome de arquivo de destino como parte da URL de destino, embora o token SAS ainda seja para o contêiner.

Esta solicitação de exemplo mostra um único documento traduzido em dois idiomas de destino.

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

Códigos de status de resposta

Veja a seguir os possíveis códigos de status HTTP retornados por uma solicitação.

Código de status	Descrição
202	Aceita. A solicitação bem-sucedida e a solicitação de lote são criadas pelo serviço. O cabeçalho Operation-Location indicará uma URL de status com operação ID.HeadersOperation-Location: string
400	Solicitação inválida. Solicitação inválida. Verifique os parâmetros de entrada.
401	Não autorizado. Verifique suas credenciais.
429	A taxa de solicitação é muito alta.
500	Erro Interno do Servidor.
503	O serviço está indisponível no momento. Tente novamente depois.
Outros códigos de status	• Excesso de pedidos • Servidor temporário indisponível

Resposta de erro

Parâmetro de chave	Tipo	Descrição
code	`string`	Enumerações contendo códigos de erro de alto nível. Valores possíveis: InternalServerError InvalidArgument InvalidRequest RequestRateTooHigh ResourceNotFound ServiceUnavailable Não Autorizado
mensagem	`string`	Obtém uma mensagem de erro de alto nível.
innerError	InnerTranslationError	Novo formato de erro interno, em conformidade com as Diretrizes da API dos serviços de IA do Azure. Essa mensagem de erro contém propriedades necessárias: ErrorCode, mensagem e destino de propriedades opcionais, detalhes (par de valores de chave) e erro interno (pode ser aninhado).
inner.Errorcode	`string`	Obtém a cadeia de caracteres de erro do código.
innerError.message	`string`	Obtém uma mensagem de erro de alto nível.
innerError.target	`string`	Obtém a fonte do erro. Por exemplo, seria `documents` ou `document id` se o documento for inválido.

Exemplos

Exemplo de resposta bem-sucedida

As informações a seguir são retornadas em uma resposta bem-sucedida.

Você pode encontrar a ID do trabalho no valor da URL Operation-Location do cabeçalho de resposta do método POST. O último parâmetro da URL é o job ID da operação (a cadeia de caracteres após "/operation/").

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

Exemplo de resposta com erro

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

Próximas etapas

Siga nosso guia de início rápido para saber mais sobre como usar a Tradução de Documento e a biblioteca de clientes.

Introdução à Tradução de Documento