RouteRequestRouteDirectionsBatch202Response interface

A API é uma solicitação de HTTP que envia lotes de consultas para a API Obter Direções de Rota usando uma única solicitação assíncrona. Você pode chamar Route Directions Batch API para ser executada de forma assíncrona (assíncrona) ou síncrona (sincronização). A API assíncrona permite que o chamador agrupe até 700 consultas e sincronize a API até 100 consultas. Para chamar a API Post Route Directions Batch em uma solicitação síncrona, consulte Post Route Directions Batch Sync.

Enviar solicitação de lote assíncrona

A API assíncrona é apropriada para processar grandes volumes de solicitações de rota relativamente complexas

• Ele permite a recuperação de resultados em uma chamada separada (vários downloads são possíveis).
• A API assíncrona é otimizada para confiabilidade e não se espera que atinja um tempo limite.
• O número de itens de lote é limitado a 700 para esta API.

Quando você faz uma solicitação usando uma solicitação assíncrona, por padrão, o serviço retorna um código de resposta 202 ao longo de uma URL de redirecionamento no campo Local do cabeçalho da resposta. Este URL deve ser verificado periodicamente até que os dados de resposta ou informações de erro estejam disponíveis. As respostas assíncronas são armazenadas por 24 horas. O URL de redirecionamento retorna uma resposta 404 se usado após o período de expiração.

Observe que a solicitação de lote assíncrona é uma operação de longa duração. Aqui está uma sequência típica de operações:

1. O Cliente envia um Lote de Direções de Rota POST pedido para o Azure Maps.

POST https://atlas.microsoft.com/route/directions/batch/json?api-version=1.0&subscription-key={subscription-key}

2. O servidor responderá com uma das seguintes opções:

   HTTP 202 Accepted - A solicitação de lote foi aceita.

   Error HTTP - Ocorreu um erro ao processar o seu pedido em lote. Pode ser um 400 Bad Request ou qualquer outro código de status Error.

3. Se a solicitação em lote foi aceita com êxito, o cabeçalho Location na resposta contém a URL para baixar os resultados da solicitação em lote. Esse URI de status tem a seguinte aparência:

GET https://atlas.microsoft.com/route/directions/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

4. O cliente emite uma solicitação de GET no URL de download do obtido na Etapa 3 para baixar os resultados do lote.

Corpo POST para solicitação de lote

Para enviar as direções de rota consultas, você usará uma solicitação de POST onde o corpo da solicitação conterá a matriz batchItems em json formato e o cabeçalho Content-Type será definido como application/json. Aqui está um corpo de solicitação de exemplo contendo 3 direções de rota consultas:

{
    "batchItems": [
        { "query": "?query=47.620659,-122.348934:47.610101,-122.342015&travelMode=bicycle&routeType=eco&traffic=false" },
        { "query": "?query=40.759856,-73.985108:40.771136,-73.973506&travelMode=pedestrian&routeType=shortest" },
        { "query": "?query=48.923159,-122.557362:32.621279,-116.840362" }
    ]
}

Uma direções de rota consulta em um lote é apenas uma de URL parcial, sem o protocolo, a URL base, o caminho, a versão da api e a chave de assinatura. Ele pode aceitar qualquer uma das direções de rota de suportadasparâmetros de URI. Os valores de cadeia de caracteres nas direções de rota consulta devem ser escapados corretamente (por exemplo, " caractere deve ser escapado com \ ) e também devem ser codificados corretamente por URL.

A API assíncrona permite que o chamador agrupe até 700 consultas e sincronize a API até 100 consultas, e o lote deve conter pelo menos 1 consulta.

Baixar resultados de lote assíncronos

Para baixar os resultados do lote assíncrono, você emitirá uma solicitação de GET para o ponto de extremidade de download em lote. Este URL de download pode ser obtido a partir do cabeçalho Location de uma solicitação de lote de POST bem-sucedida e tem a seguinte aparência:

https://atlas.microsoft.com/route/directions/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

Aqui está a sequência típica de operações para baixar os resultados do lote:

1. O cliente envia uma solicitação de GET usando o URL de download .

2. O servidor responderá com uma das seguintes opções:

   HTTP 202 Accepted - A solicitação em lote foi aceita, mas ainda está sendo processada. Por favor, tente novamente dentro de algum tempo.

   HTTP 200 OK - Solicitação em lote processada com sucesso. O corpo da resposta contém todos os resultados do lote.

Modelo de resposta em lote

O conteúdo de dados retornado é semelhante para solicitações assíncronas e de sincronização. Ao baixar os resultados de uma solicitação de lote assíncrona, se o lote tiver terminado o processamento, o corpo da resposta conterá a resposta em lote. Essa resposta em lote contém um componente summary que indica os totalRequests que faziam parte da solicitação de lote original e successfulRequestsou seja, consultas que foram executadas com êxito. A resposta em lote também inclui uma matriz batchItems que contém uma resposta para cada consulta na solicitação em lote. O batchItems conterá os resultados exatamente na mesma ordem em que as consultas originais foram enviadas na solicitação de lote. Cada item no batchItems contém statusCode e response campos. Cada response em batchItems é de um dos seguintes tipos:

• RouteDirections - Se a consulta foi concluída com êxito.

• Error - Se a consulta falhou. Neste caso, a resposta conterá um code e um message.

Aqui está um exemplo de resposta em lote com 1 bem-sucedido e 1 resultado falhado:

{
    "summary": {
        "successfulRequests": 1,
        "totalRequests": 2
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response": {
                "routes": [
                    {
                        "summary": {
                            "lengthInMeters": 1758,
                            "travelTimeInSeconds": 387,
                            "trafficDelayInSeconds": 0,
                            "departureTime": "2018-07-17T00:49:56+00:00",
                            "arrivalTime": "2018-07-17T00:56:22+00:00"
                        },
                        "legs": [
                            {
                                "summary": {
                                    "lengthInMeters": 1758,
                                    "travelTimeInSeconds": 387,
                                    "trafficDelayInSeconds": 0,
                                    "departureTime": "2018-07-17T00:49:56+00:00",
                                    "arrivalTime": "2018-07-17T00:56:22+00:00"
                                },
                                "points": [
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.34892
                                    },
                                    {
                                        "latitude": 47.62094,
                                        "longitude": -122.3485
                                    },
                                    {
                                        "latitude": 47.62095,
                                        "longitude": -122.3476
                                    }
                                ]
                            }
                        ],
                        "sections": [
                            {
                                "startPointIndex": 0,
                                "endPointIndex": 40,
                                "sectionType": "TRAVEL_MODE",
                                "travelMode": "bicycle"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}