Iniciar a tradução em lote

Artigo
09/26/2024

Recurso de referência
: Azure AI Translator → Document Translation
API Versão: 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 seus documentos de origem e traduzidos.

URL do Pedido

Importante

Todas as solicitações de API para o recurso Tradução de Documentos 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 do pedido

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

Cabeçalhos	Description	Condição
ocp-apim-subscription-key	Sua chave de API de serviço do Translator no portal do Azure.	Obrigatório
OCP-Apim-Assinatura-Região	A região onde o recurso foi criado.	Necessário ao usar um recurso regional (geográfico) como West US. e bala.
Tipo de conteúdo	O tipo de conteúdo da carga útil. O valor aceito é application/json ou charset=UTF-8.	Obrigatório

BatchRequest (corpo)

Cada solicitação pode conter vários documentos e deve conter um contêiner de origem e destino para cada documento. Tipos de suportes de origem: application/json, text/json, application/*+json.
O filtro de prefixo e sufixo (se fornecido) são usados para filtrar pastas. O prefixo é aplicado ao subcaminho após o nome do contêiner.
Glossários podem ser incluídos no pedido. Se o glossário for inválido ou inacessível durante a tradução, será indicado um erro no estado do documento.
Se já existir um arquivo com o mesmo nome no destino de destino, o trabalho falhará.
O 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.xlf",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
}

Entradas

Definição para a solicitação de conversão em lote de entrada.

Parâmetro-chave	Type	Necessário	Parâmetros de solicitação	Description
Insumos	`array`	True	• origem (objeto) • destinos (matriz) • storageType (string)	Dados de origem de entrada.

entradas.fonte

Definição dos dados de origem.

Parâmetro-chave	Type	Necessário	Parâmetros de solicitação	Description
entradas.fonte	`object`	True	• sourceUrl (string) • filter (objeto) • language (string) • storageSource (string)	Dados de origem para documentos de entrada.
inputs.source.sourceUrl	`string`	True	• corda	Local do contêiner para o arquivo ou pasta de origem.
inputs.source.filter	`object`	False	• prefixo (string) • sufixo (string)	Cadeias de caracteres que diferenciam maiúsculas de minúsculas para filtrar documentos no caminho de origem.
inputs.source.filter.prefix	`string`	False	• corda	Cadeia de caracteres de prefixo que diferencia maiúsculas de minúsculas para filtrar documentos no caminho de origem para tradução. Muitas vezes usado para designar subpastas para tradução. Exemplo: "FolderA".
inputs.source.filter.sufixo	`string`	False	• corda	Cadeia 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. Exemplo: ".txt"
inputs.source.language	`string`	False	• corda	O código de idioma para os documentos de origem. Se não for especificado, a deteção automática será implementada.
inputs.source.storageSource	`string`	False	• corda	Fonte de armazenamento para entradas. O padrão é `AzureBlob`.

entradas.alvos

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

Parâmetro-chave	Type	Necessário	Parâmetros de solicitação	Description
entradas.alvos	`array`	True	• targetUrl (string) • category (string) • language (string) • glossários (array) • storageSource (string)	Dados de metas e glossários para documentos traduzidos.
inputs.targets.targetUrl	`string`	True	• corda	Localização do local do contêiner para documentos traduzidos.
entradas.targets.category	`string`	False	• corda	Classificação ou categoria para o pedido de tradução. Exemplo: geral.
inputs.targets.language	`string`	True	• corda	Código da língua de chegada. Exemplo: "fr".
inputs.targets.glossários	`array`	False	• glossárioUrl (string) • formato (string) • versão (string) • storageSource (string)	Consulte Criar e usar glossários
inputs.targets.glossaries.glossaryUrl	`string`	True (se usar glossários)	• corda	Localização do glossário. A extensão do arquivo é usada para extrair a formatação se o parâmetro format 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.glossários.format	`string`	False	• corda	Formato de arquivo especificado para glossário. Para verificar se o formato de ficheiro é suportado, consulte Obter formatos de glossário suportados.
inputs.targets.glossaries.version	`string`	False	• corda	Indicador de versão. Exemplo: "2.0".
inputs.targets.glossaries.storageSource	`string`	False	• corda	Fonte de armazenamento para glossários. O padrão é `_AzureBlob_`.
inputs.targets.storageSource	`string`	False	• corda	Origem de armazenamento para targets.defaults para `_AzureBlob_`.

inputs.storageType

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

Parâmetro-chave	Type	Necessário	Parâmetros de solicitação	Description
inputs.storageType	`string`	False	•`Folder` • `File`	Tipo de armazenamento da cadeia de caracteres de origem dos documentos de entrada. Apenas "Pasta" ou "Ficheiro" são valores válidos.

Opções

Definição para a solicitação de conversão em lote de entrada.

Parâmetro-chave	Type	Necessário	Parâmetros de solicitação	Description
Opções	`object`	False	Fonte de informações para documentos de entrada.
opções.experimentais	`boolean`	False	•`true` • `false`	Indica se a solicitação inclui um recurso experimental (se aplicável). Apenas os booleanos `true` ou `false` são valores válidos.

Pedido de exemplo

Seguem-se exemplos de pedidos em lote.

Nota

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

Traduzir todos os documentos num contentor

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

                }
            ]
        }
    ]
}

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

Traduzindo documento específico em um contêiner

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

Este pedido de exemplo mostra um único documento traduzido em duas línguas de chegada.

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

Gorjeta

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 URL do cabeçalho Operation-Location de resposta do método POSTstart-batch-translation. A cadeia alfanumérica que segue o /document/ parâmetro é o trabalho idda operação:

Cabeçalho da resposta URL de resposta

Local de Operação {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 da resposta	URL de resposta
Local de Operação	{document-translation-endpoint}/translator/document/`9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec`?api-version=2024-05-01

Códigos de status de resposta

A seguir estão os possíveis códigos de status HTTP que uma solicitação retorna.

Código de Estado	Description
202	Aceito. Solicitação bem-sucedida e a solicitação em lote criada. O cabeçalho Operation-Location indica uma url de status com a operação ID.HeadersOperation-Location: string
400	Mau pedido. Pedido inválido. Verifique os parâmetros de entrada.
401	Não autorizado. Verifique as 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 mais tarde.
Outros códigos de status	• Demasiados pedidos. O servidor está temporariamente indisponível

Resposta de erro

Parâmetro-chave	Tipo	Description
code	`string`	Enums contendo códigos de erro de alto nível. Valores possíveis:</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Não autorizado
mensagem	`string`	Obtém mensagem de erro de alto nível.
innerError	InnerTranslationError	Novo formato de Erro Interno que está em conformidade com as Diretrizes da API de serviços de IA do Azure. Esta mensagem de erro contém as propriedades necessárias: ErrorCode, mensagem e destino de propriedades opcionais, detalhes (par de valores de chave) e erro interno (pode ser aninhado).
interior. Código de erro	`string`	Obtém a cadeia de erro de código.
innerError.message	`string`	Obtém mensagem de erro de alto nível.
innerError.target	`string`	Obtém a origem do erro. Por exemplo, seria `documents` ou `document id` se o documento é inválido.

Exemplo de resposta de erro

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

Próximos passos

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

Introdução à Tradução de Documentos

Partilhar via