Share via

API V2 de operação de execução prolongada do criador

  • Artigo

Algumas APIs no Azure Mapas usam um Padrão de solicitação assíncrona-resposta. Esse padrão permite que o Azure Mapas forneça serviços altamente disponíveis e responsivos. Este artigo explica a implementação específica do processamento em segundo plano assíncrono de execução prolongada do Azure Mapa.

Para enviar uma solicitação

Um aplicativo cliente inicia uma operação de execução prolongada por meio de uma chamada síncrona para uma API HTTP. Normalmente, essa chamada está na forma de uma solicitação HTTP POST. Quando uma carga de trabalho assíncrona é criada, a API retorna um código de status HTTP 202, indicando que a solicitação foi aceita. Essa resposta contém um cabeçalho Location apontando para um ponto de extremidade que o cliente pode sondar para verificar o status da operação de execução prolongada.

Exemplo de uma resposta de êxito

Status: 202 Accepted
Operation-Location: https://atlas.microsoft.com/service/operations/{operationId}

Se a chamada não passar na validação, a API retorna uma resposta HTTP 400, indicando um Bad Request. O corpo da resposta fornece ao cliente mais informações sobre o motivo de a solicitação ser inválida.

Monitorar o status da operação

O ponto de extremidade de localização fornecido nos cabeçalhos de resposta aceitos pode ser sondado para verificar o status da operação de execução prolongada. O corpo da resposta da solicitação de status da operação sempre contém as propriedades status e created. A propriedade status mostra o estado atual da operação de execução prolongada. Os estados possíveis incluem "NotStarted", "Running", "Succeeded" e "Failed". A propriedade created mostra a hora em que a solicitação inicial foi feita para iniciar a operação de execução prolongada. Quando o estado é "NotStarted" ou "Running", um cabeçalho Retry-After também é fornecido com a resposta. O cabeçalho Retry-After, medido em segundos, pode ser usado para determinar quando deve ser feita a próxima chamada de sondagem para a API de status de operação.

Exemplo de execução de uma resposta de status

Status: 200 OK
Retry-After: 30
{
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "created": "3/11/2020 8:45:13 PM +00:00",
    "status": "Running"
}

Processar a conclusão da operação

Após a conclusão da operação de execução prolongada, o status da resposta é "Succeeded" ou "Failed". Todas as respostas retornam um código HTTP 200 OK. Quando um novo recurso for criado a partir de uma operação de execução prolongada, a resposta também contém um cabeçalho Resource-Location que aponta para os metadados sobre o recurso. No caso de falha, a resposta tem uma propriedade error no corpo. Os dados de erro aderem à especificação de erro do OData (Protocolo Open Data).

Exemplo de uma resposta de êxito

Status: 200 OK
Resource-Location: "https://atlas.microsoft.com/tileset/{tileset-id}"
 {
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "created": "2021-05-06T07:55:19.5256829+00:00",
    "status": "Succeeded"
}

Exemplo de resposta de falha

Status: 200 OK

{
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "created": "3/11/2020 8:45:13 PM +00:00",
    "status": "Failed",
    "error": {
        "code": "InvalidFeature",
        "message": "The provided feature is invalid.",
        "details": {
            "code": "NoGeometry",
            "message": "No geometry was provided with the feature."
        }
    }
}