Compartilhar via

Obter status de todos os documentos

  • Artigo

Recurso de referência
: Azure AI Translator → Versão da API de Tradução de Documentos
: 2024-05-01
Método HTTP: GET

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.

  • Use o get documents status método para solicitar o status de todos os documentos em um trabalho de tradução.

  • Os parâmetros de consulta $top, $skip e $maxpagesize podem ser usados para especificar um número de resultados a serem retornados e um deslocamento para a coleção.

    • $top indica o número total de registros que o usuário deseja retornar em todas as páginas.
    • $skip indica o número de registros a serem ignorados da lista de status do documento mantida pelo servidor com base no método de classificação especificado. Por padrão, os registros são classificados por hora de início decrescente.
    • $maxpagesize é o máximo de itens retornados em uma página.
    • Se mais itens forem solicitados por meio de $top (ou se $top não for especificado e houver mais itens a serem retornados), @nextLink conterá o link para a próxima página.
    • Se o número de documentos na resposta ultrapassar nosso limite de paginação, a paginação do servidor será usada.
    • Respostas paginadas indicam um resultado parcial e incluem um token de continuação na resposta. A ausência de um token de continuação significa que não há nenhuma página adicional disponível.

Observação

Se o servidor não puder honrar $top e/ou $skip, ele precisará retornar um erro para o cliente informando isso, em vez de apenas ignorar as opções de consulta. Isso reduz o risco de o cliente fazer suposições sobre os dados retornados.

  • $orderBy query pode ser usado para classificar a lista retornada (ex: $orderBy=createdDateTimeUtc asc ou $orderBy=createdDateTimeUtc desc).
  • A classificação padrão é decrescente em createdDateTimeUtc. Alguns parâmetros de consulta podem ser usados para filtrar a lista retornada (ex: status=Succeeded,Cancelled) retorna apenas documentos bem-sucedidos e cancelados.
  • Os createdDateTimeUtcStart parâmetros de consulta and createdDateTimeUtcEnd podem ser usados combinados ou separadamente para especificar um intervalo de datetime para filtrar a lista retornada.
  • Os parâmetros de consulta de filtragem suportados são (status, id, createdDateTimeUtcStarte createdDateTimeUtcEnd).
  • Quando $top e $skip estão incluídos, o servidor deve primeiro aplicar $skip e, depois, $top à coleção.

URL da solicitação

Envie uma solicitação GET para:

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

Localizando o valor id

  • 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.

Parâmetros da solicitação

Os parâmetros de solicitação passados na cadeia de caracteres de consulta são:

Parâmetro de consulta Em Obrigatório Type Descrição
id caminho True string A ID da operação.
$maxpagesize consulta Falso integer int32 $maxpagesize é o máximo de itens retornados em uma página. Se mais itens forem solicitados por meio de $top (ou se $top não for especificado e houver mais itens a serem retornados), @nextLink conterá o link para a próxima página. Os clientes podem solicitar paginação controlada por servidor com um tamanho de página específico especificando uma $maxpagesize preferência. O servidor DEVERÁ seguir essa preferência se o tamanho da página especificado for menor que o tamanho da página padrão do servidor.
$orderBy Consulta Falso array A consulta de classificação para a coleção (ex: CreatedDateTimeUtc asc, CreatedDateTimeUtc desc).
$skip consulta Falso integer int32 $skip indica o número de registros a serem ignorados da lista de registros mantida pelo servidor com base no método de classificação especificado. Por padrão, a classificação é por hora de início decrescente. Os clientes PODEM usar os parâmetros de consulta $top e $skip para especificar um número de resultados a serem retornados e um deslocamento para a coleção. Quando o cliente retornar $top e $skip, o servidor DEVERÁ aplicar primeiro $skip e, em seguida, $top na coleção. Se o servidor não puder honrar $top e/ou $skip, o servidor DEVE retornar um erro ao cliente informando sobre isso, em vez de apenas ignorar as opções de consulta.
$top consulta Falso integer int32 $top indica o número total de registros que o usuário deseja retornar em todas as páginas. Os clientes podem usar $top e $skip consultar parâmetros para especificar o número de resultados a serem retornados e um deslocamento na coleção. Quando o cliente retornar $top e $skip, o servidor DEVERÁ aplicar primeiro $skip e, em seguida, $top na coleção. Se o servidor não puder honrar $top e/ou $skip, o servidor DEVE retornar um erro ao cliente informando sobre isso, em vez de apenas ignorar as opções de consulta.
createdDateTimeUtcEnd Consulta Falso string date-time O datetime final do período de obtenção dos itens.
createdDateTimeUtcStart Consulta Falso string date-time O datetime inicial do período de obtenção dos itens.
ids consulta Falso array IDs a serem usadas na filtragem.
status Consulta Falso array Status a serem usados na filtragem.

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 do serviço Tradutor do 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 Oeste dos EUA
Content-Type O tipo de conteúdo da carga. Os valores aceitos são application/json ou charset=UTF-8. Obrigatório

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
200 OK. Solicitação bem-sucedida e retorna o status dos documentos. HeadersRetry-After: integerETag: string
400 Solicitação inválida. Verifique os parâmetros de entrada.
401 Não autorizado. Verifique suas credenciais.
404 O recurso não foi encontrado.
500 Erro Interno do Servidor.
Outros códigos de status • Muitos pedidos
• O servidor está temporariamente indisponível

Resposta de Obter status do documento

Resposta bem-sucedida de Obter status do documento

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

Nome Tipo Descrição
@nextLink string URL da próxima página. Nulo se não houver mais nenhuma página disponível.
value DocumentStatus [] A lista de status detalhada de documentos individuais.
value.path string Localização do documento ou da pasta.
value.sourcePath string Localização do documento de origem.
value.createdDateTimeUtc string Data e hora de criação da operação.
value.lastActionDateTimeUtc string Data e hora em que o status da operação é atualizado.
value.status status Lista de status possíveis para o trabalho ou o documento.
• Cancelado
•Cancelar
•Falhou
• Não iniciado
•Executando
•Conseguiu
• Falha na validação
value.to string Idioma de destino.
value.progress número Progresso da tradução se disponível.
value.id string ID do documento.
value.characterCharged Número inteiro Caracteres cobrados pela API.

Resposta de erro

Nome Tipo Descrição
code string Enumerações contendo códigos de erro de alto nível. Valores possíveis:
• Erro de servidor interno
• Argumento inválido
• Solicitação inválida
• RequestRateTooHigh
• ResourceNotFound
• ServiçoIndisponível
•Desautorizado
message string Obtém uma mensagem de erro de alto nível.
destino string Obtém a fonte do erro. Por exemplo, seria documents ou document id para um documento inválido.
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 as propriedades obrigatórias ErrorCode e message, bem como as propriedades opcionais target, details (par chave-valor) e innerError (pode ser aninhado).
innerError.code 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 houvesse um documento inválido.

Exemplos

Dica

Use esse método para recuperar o documentId parâmetro para a cadeia de caracteres de consulta get-document-status .

Exemplo de resposta bem-sucedida

O objeto JSON a seguir é um exemplo de uma resposta bem-sucedida.

{
  "value": [
    {
      "path": "https://myblob.blob.core.windows.net/destinationContainer/fr/mydoc.txt",
      "sourcePath": "https://myblob.blob.core.windows.net/sourceContainer/fr/mydoc.txt",
      "createdDateTimeUtc": "2020-03-26T00:00:00Z",
      "lastActionDateTimeUtc": "2020-03-26T01:00:00Z",
      "status": "Running",
      "to": "fr",
      "progress": 0.1,
      "id": "273622bd-835c-4946-9798-fd8f19f6bbf2",
      "characterCharged": 0
    }
  ],
  "@nextLink": "https://westus.cognitiveservices.azure.com/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55/documents?$top=5&$skip=15"
}

Exemplo de resposta com erro

O objeto JSON a seguir é um exemplo de uma resposta com erro. O esquema dos outros códigos de erro é o mesmo.

Código de status: 500

{
  "error": {
    "code": "InternalServerError",
    "message": "Internal Server Error",
    "target": "Operation",
    "innerError": {
      "code": "InternalServerError",
      "message": "Unexpected internal server error has occurred"
    }
  }
}

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