Obter status de documentos

  • Artigo

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

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.

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, a classificação é 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.

O parâmetro de consulta $orderBy pode ser usado para classificar a lista retornada (por exemplo, "$orderBy=createdDateTimeUtc asc" ou "$orderBy=createdDateTimeUtc desc"). A classificação padrão é decrescente por createdDateTimeUtc. Alguns parâmetros de consulta podem ser usados para filtrar a lista retornada. Por exemplo, "status=Succeeded,Cancelled" retorna apenas documentos bem-sucedidos e cancelados. createdDateTimeUtcStart e 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 com suporte são (status, IDs, createdDateTimeUtcStart e createdDateTimeUtcEnd).

Quando $top e $skip estão incluídos, o servidor deve primeiro aplicar $skip e, depois, $top à coleção.

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.

URL da solicitação

Envie uma solicitação GET para:

GET https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches/{id}/documents

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.

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 path 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 matriz 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 consultar parâmetros para especificar o número de resultados a serem retornados e $skip 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
Ocp-Apim-Subscription-Key Cabeçalho de solicitação necessá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 • Excesso de 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ãoIniciado
•Executando
•Conseguiu
• ValidaçãoFalhou
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:
• InternalServerError
• 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

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