Iniciar tradução em lote

Artigo
06/01/2024

Referência
Recurso: Tradutor de IA do Azure → Tradução de Documento
Versão da API: 2024-05-01
Método HTTP: POST

Use o método para executar uma solicitação de conversão em lote assíncrona Start Translation .
O método requer uma conta de armazenamento de Blob do Azure com contêineres de armazenamento para sua origem e documentos traduzidos.

URL de solicitação

Importante

Todas as solicitações de API para o recurso de Tradução de Documento exigem um ponto de extremidade de domínio personalizado localizado na página de visão geral do recurso no portal do Azure.

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

Cabeçalhos da solicitação

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

Cabeçalhos	Descrição	Condição
Ocp-Apim-Subscription-Key	Sua chave de API de serviço do Tradutor no portal do Azure.	Obrigatório
Ocp-Apim-Subscription-Region	A região em que o recurso foi criado.	• Obrigatório ao usar um recurso regional (geográfico) como West US. &bala.
Content-Type	O tipo de conteúdo da carga. Os valores aceitos são application/json ou charset=UTF-8.	• Obrigatório

BatchRequest (corpo)

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.
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.
Glossários podem ser incluídos na solicitação. 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 de destino, o trabalho falhará.
A targetUrl para cada idioma de destino deve ser exclusivo.


{
  "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)	Consulte Criar 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, consulte Obter 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 targets.defaults para `_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?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

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

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

                }
            ]
        }
    ]
}

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?{SAS-token-query-string}",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "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?{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"
                }
            ]
        }
    ]
}

Dica

Esse método retorna o parâmetro job id para as cadeias de caracteres de consulta get-translation-status, get-documents-status, get-document-status e cancel-translation request.

Você pode encontrar o trabalho id no valor da URL Operation-Location do cabeçalho de resposta start-batch-translation do método POST. A cadeia de caracteres alfanumérica seguindo o parâmetro /document/ é o trabalho da operaçãoid:

Cabeçalho de resposta URL da Resposta

Operation-Location {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01
Você também pode usar uma solicitação get-translations-status para recuperar uma lista de trabalhos de tradução e seus ids.

Cabeçalho de resposta	URL da Resposta
Operation-Location	{document-translation-endpoint}/translator/document/`9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec`?api-version=2024-05-01

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	• Muitos pedidos. O servidor está temporariamente indisponível

Resposta de erro

Parâmetro de chave	Tipo	Descrição
código	`string`	Enumerações contendo códigos de erro de alto nível. Valores possíveis:</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Unauthorized
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.

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

Compartilhar via