Obter status de traduções

  • Artigo

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

O método Obter status de traduções retorna uma lista das solicitações em lote enviadas e o status de cada solicitação. Essa lista contém apenas as solicitações em lotes enviadas pelo usuário (com base no recurso).

Se o número de solicitações 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 lotes 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" retornará apenas as operações bem-sucedidas e canceladas. 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).

O servidor honra os valores especificados pelo cliente. No entanto, os clientes precisam estar preparados para lidar com respostas com um tamanho de página diferente ou com um token de continuação.

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

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
$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 a paginação controlada por servidor com um tamanho de página determinado especificando uma preferência $maxpagesize. 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 $top e $skip são fornecidos por um cliente, o servidor DEVE primeiro aplicar $skip e depois $top à coleção. Observação: se o servidor não puder seguir $top e/ou $skip, ele DEVERÁ retornar um erro ao cliente informando 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 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 $top e $skip são fornecidos por um cliente, o servidor DEVE primeiro aplicar $skip e depois $top à coleção. Observação: se o servidor não puder seguir $top e/ou $skip, ele DEVERÁ retornar um erro ao cliente informando 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, retorna o status de todas as operações. HeadersRetry-After: integerETag: string
400 Solicitação inválida. Solicitação inválida. Verifique os parâmetros de entrada.
401 Não autorizado. Verifique suas credenciais.
500 Erro Interno do Servidor.
Outros códigos de status • Excesso de pedidos
• Servidor temporário indisponível

Resposta do método Obter status de traduções

Resposta bem-sucedida do método Obter status de traduções

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 TranslationStatus[] Matriz TranslationStatus[]
value.id string Identificador da operação.
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 foi atualizado.
value.status String Lista de status possíveis para o trabalho ou o documento:
• Cancelado
•Cancelar
•Falhou
• NãoIniciado
•Executando
•Conseguiu
• ValidaçãoFalhou
value.summary StatusSummary[] Resumo que contém os detalhes listados abaixo.
value.summary.total Número inteiro Número total de documentos.
value.summary.failed Número inteiro Número de documentos com falha.
value.summary.success Número inteiro Número de documentos traduzidos com sucesso.
value.summary.inProgress Número inteiro Número de documentos em andamento.
value.summary.notYetStarted Número inteiro Número de documentos cujo processamento ainda não começou.
value.summary.cancelled Número inteiro Número de documentos cancelados.
value.summary.totalCharacterCharged Número inteiro Número total de caracteres cobrados.

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 se houvesse 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": [
        {
            "id": "36724748-f7a0-4db7-b7fd-f041ddc75033",
            "createdDateTimeUtc": "2021-06-18T03:35:30.153374Z",
            "lastActionDateTimeUtc": "2021-06-18T03:36:44.6155316Z",
            "status": "Succeeded",
            "summary": {
                "total": 3,
                "failed": 2,
                "success": 1,
                "inProgress": 0,
                "notYetStarted": 0,
                "cancelled": 0,
                "totalCharacterCharged": 0
            }
        },
        {
            "id": "1c7399a7-6913-4f20-bb43-e2fe2ba1a67d",
            "createdDateTimeUtc": "2021-05-24T17:57:43.8356624Z",
            "lastActionDateTimeUtc": "2021-05-24T17:57:47.128391Z",
            "status": "Failed",
            "summary": {
                "total": 1,
                "failed": 1,
                "success": 0,
                "inProgress": 0,
                "notYetStarted": 0,
                "cancelled": 0,
                "totalCharacterCharged": 0
            }
        },
        {
            "id": "daa2a646-4237-4f5f-9a48-d515c2d9af3c",
            "createdDateTimeUtc": "2021-04-14T19:49:26.988272Z",
            "lastActionDateTimeUtc": "2021-04-14T19:49:43.9818634Z",
            "status": "Succeeded",
            "summary": {
                "total": 2,
                "failed": 0,
                "success": 2,
                "inProgress": 0,
                "notYetStarted": 0,
                "cancelled": 0,
                "totalCharacterCharged": 21899
            }
        }
    ],
    ""@nextLink": "https://westus.cognitiveservices.azure.com/translator/text/batch/v1.1/operations/727BF148-F327-47A0-9481-ABAE6362F11E/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