Skip to content

[Hub Generated] Review request for Microsoft.Maps/Microsoft.Maps to add version preview/1.0 #14965

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lmazuel merged 1 commit into from
Jun 29, 2021
Merged

[Hub Generated] Review request for Microsoft.Maps/Microsoft.Maps to add version preview/1.0 #14965

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion specification/maps/data-plane/Microsoft.Maps/Route/preview/1.0/route.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1608,7 +1608,7 @@
"/route/directions/batch/{format}": {
"post": {
"x-publish": true,
"description": "**Route Directions Batch API**\n\n\n**Applies to**: S1 pricing tier.\n\n\n\nThe Route Directions Batch API sends batches of queries to [Route Directions API](https://docs.microsoft.com/en-us/rest/api/maps/route/getroutedirections) using just a single API call. You can call Route Directions Batch API to run either asynchronously (async) or synchronously (sync). The async API allows caller to batch up to **700** queries and sync API up to **100** queries.\n### Submit Synchronous Batch Request\nThe Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API.\n```\nPOST https://atlas.microsoft.com/route/directions/batch/sync/json?api-version=1.0&subscription-key={subscription-key}\n```\n### Submit Asynchronous Batch Request\nThe Asynchronous API is appropriate for processing big volumes of relatively complex route requests\n- It allows the retrieval of results in a separate call (multiple downloads are possible).\n- The asynchronous API is optimized for reliability and is not expected to run into a timeout.\n- The number of batch items is limited to **700** for this API.\n\nWhen you make a request by using async request, by default the service returns a 202 response code along a redirect URL in the Location field of the response header. This URL should be checked periodically until the response data or error information is available.\nThe asynchronous responses are stored for **14** days. The redirect URL returns a 404 response if used after the expiration period.\n\nPlease note that asynchronous batch request is a long-running request. Here's a typical sequence of operations:\n1. Client sends a Route Directions Batch `POST` request to Azure Maps\n2. The server will respond with one of the following:\n\n > HTTP `202 Accepted` - Batch request has been accepted.\n\n > HTTP `Error` - There was an error processing your Batch request. This could either be a `400 Bad Request` or any other `Error` status code.\n\n3. If the batch request was accepted successfully, the `Location` header in the response contains the URL to download the results of the batch request.\n This status URI looks like following:\n\n``` GET https://atlas.microsoft.com/batch/{batch-id}?api-version=1.0 ```\nNote:- Please remember to add AUTH information (subscription-key/azure_auth - See [Security](#security)) to the _status URI_ before running it. <br>\n4. Client issues a `GET` request on the _download URL_ obtained in Step 3 to download the batch results.\n\n### POST Body for Batch Request\nTo send the _route directions_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 3 _route directions_ queries:\n\n\n```json\n{\n \"batchItems\": [\n { \"query\": \"?query=47.620659,-122.348934:47.610101,-122.342015&travelMode=bicycle&routeType=eco&traffic=false\" },\n { \"query\": \"?query=40.759856,-73.985108:40.771136,-73.973506&travelMode=pedestrian&routeType=shortest\" },\n { \"query\": \"?query=48.923159,-122.557362:32.621279,-116.840362\" }\n ]\n}\n```\n\nA _route directions_ query in a batch is just a partial URL _without_ the protocol, base URL, path, api-version and subscription-key. It can accept any of the supported _route directions_ [URI parameters](https://docs.microsoft.com/en-us/rest/api/maps/route/getroutedirections#uri-parameters). The string values in the _route directions_ query must be properly escaped (e.g. \" character should be escaped with \\\\ ) and it should also be properly URL-encoded.\n\n\nThe async API allows caller to batch up to **700** queries and sync API up to **100** queries, and the batch should contain at least **1** query.\n\n\n### Download Asynchronous Batch Results\nTo download the async batch results you will issue a `GET` request to the batch download endpoint. This _download URL_ can be obtained from the `Location` header of a successful `POST` batch request and looks like the following:\n\n```\nhttps://atlas.microsoft.com/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}\n```\nHere's the typical sequence of operations for downloading the batch results:\n1. Client sends a `GET` request using the _download URL_.\n2. The server will respond with one of the following:\n \n > HTTP `202 Accepted` - Batch request was accepted but is still being processed. Please try again in some time.\n\n > HTTP `200 OK` - Batch request successfully processed. The response body contains all the batch results.\n\n\n\n### Batch Response Model\nThe returned data content is similar for async and sync requests. When downloading the results of an async batch request, if the batch has finished processing, the response body contains the batch response. This batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests`i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item in `batchItems` contains `statusCode` and `response` fields. Each `response` in `batchItems` is of one of the following types:\n\n - [`RouteDirectionsResponse`](https://docs.microsoft.com/en-us/rest/api/maps/route/getroutedirections#routedirectionsresponse) - If the query completed successfully.\n\n - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.\n\n\nHere's a sample Batch Response with 1 _successful_ and 1 _failed_ result:\n\n\n```json\n{\n \"summary\": {\n \"successfulRequests\": 1,\n \"totalRequests\": 2\n },\n \"batchItems\": [\n {\n \"statusCode\": 200,\n \"response\": {\n \"routes\": [\n {\n \"summary\": {\n \"lengthInMeters\": 1758,\n \"travelTimeInSeconds\": 387,\n \"trafficDelayInSeconds\": 0,\n \"departureTime\": \"2018-07-17T00:49:56+00:00\",\n \"arrivalTime\": \"2018-07-17T00:56:22+00:00\"\n },\n \"legs\": [\n {\n \"summary\": {\n \"lengthInMeters\": 1758,\n \"travelTimeInSeconds\": 387,\n \"trafficDelayInSeconds\": 0,\n \"departureTime\": \"2018-07-17T00:49:56+00:00\",\n \"arrivalTime\": \"2018-07-17T00:56:22+00:00\"\n },\n \"points\": [\n {\n \"latitude\": 47.62094,\n \"longitude\": -122.34892\n },\n {\n \"latitude\": 47.62094,\n \"longitude\": -122.3485\n },\n {\n \"latitude\": 47.62095,\n \"longitude\": -122.3476\n }\n ]\n }\n ],\n \"sections\": [\n {\n \"startPointIndex\": 0,\n \"endPointIndex\": 40,\n \"sectionType\": \"TRAVEL_MODE\",\n \"travelMode\": \"bicycle\"\n }\n ]\n }\n ]\n }\n },\n {\n \"statusCode\": 400,\n \"response\":\n {\n \"error\":\n {\n \"code\": \"400 BadRequest\",\n \"message\": \"Bad request: one or more parameters were incorrectly specified or are mutually exclusive.\"\n }\n }\n }\n ]\n}\n```",
"description": "**Route Directions Batch API**\n\n\n**Applies to**: S1 pricing tier.\n\n\n\nThe Route Directions Batch API sends batches of queries to [Route Directions API](https://docs.microsoft.com/en-us/rest/api/maps/route/getroutedirections) using just a single API call. You can call Route Directions Batch API to run either asynchronously (async) or synchronously (sync). The async API allows caller to batch up to **700** queries and sync API up to **100** queries.\n### Submit Synchronous Batch Request\nThe Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API.\n```\nPOST https://atlas.microsoft.com/route/directions/batch/sync/json?api-version=1.0&subscription-key={subscription-key}\n```\n### Submit Asynchronous Batch Request\nThe Asynchronous API is appropriate for processing big volumes of relatively complex route requests\n- It allows the retrieval of results in a separate call (multiple downloads are possible).\n- The asynchronous API is optimized for reliability and is not expected to run into a timeout.\n- The number of batch items is limited to **700** for this API.\n\nWhen you make a request by using async request, by default the service returns a 202 response code along a redirect URL in the Location field of the response header. This URL should be checked periodically until the response data or error information is available.\nThe asynchronous responses are stored for **14** days. The redirect URL returns a 404 response if used after the expiration period.\n\nPlease note that asynchronous batch request is a long-running request. Here's a typical sequence of operations:\n1. Client sends a Route Directions Batch `POST` request to Azure Maps\n2. The server will respond with one of the following:\n\n > HTTP `202 Accepted` - Batch request has been accepted.\n\n > HTTP `Error` - There was an error processing your Batch request. This could either be a `400 Bad Request` or any other `Error` status code.\n\n3. If the batch request was accepted successfully, the `Location` header in the response contains the URL to download the results of the batch request.\n This status URI looks like following:\n\n``` GET https://atlas.microsoft.com/route/directions/batch/{batch-id}?api-version=1.0 ```\nNote:- Please remember to add AUTH information (subscription-key/azure_auth - See [Security](#security)) to the _status URI_ before running it. <br>\n4. Client issues a `GET` request on the _download URL_ obtained in Step 3 to download the batch results.\n\n### POST Body for Batch Request\nTo send the _route directions_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 3 _route directions_ queries:\n\n\n```json\n{\n \"batchItems\": [\n { \"query\": \"?query=47.620659,-122.348934:47.610101,-122.342015&travelMode=bicycle&routeType=eco&traffic=false\" },\n { \"query\": \"?query=40.759856,-73.985108:40.771136,-73.973506&travelMode=pedestrian&routeType=shortest\" },\n { \"query\": \"?query=48.923159,-122.557362:32.621279,-116.840362\" }\n ]\n}\n```\n\nA _route directions_ query in a batch is just a partial URL _without_ the protocol, base URL, path, api-version and subscription-key. It can accept any of the supported _route directions_ [URI parameters](https://docs.microsoft.com/en-us/rest/api/maps/route/getroutedirections#uri-parameters). The string values in the _route directions_ query must be properly escaped (e.g. \" character should be escaped with \\\\ ) and it should also be properly URL-encoded.\n\n\nThe async API allows caller to batch up to **700** queries and sync API up to **100** queries, and the batch should contain at least **1** query.\n\n\n### Download Asynchronous Batch Results\nTo download the async batch results you will issue a `GET` request to the batch download endpoint. This _download URL_ can be obtained from the `Location` header of a successful `POST` batch request and looks like the following:\n\n```\nhttps://atlas.microsoft.com/route/directions/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}\n```\nHere's the typical sequence of operations for downloading the batch results:\n1. Client sends a `GET` request using the _download URL_.\n2. The server will respond with one of the following:\n \n > HTTP `202 Accepted` - Batch request was accepted but is still being processed. Please try again in some time.\n\n > HTTP `200 OK` - Batch request successfully processed. The response body contains all the batch results.\n\n\n\n### Batch Response Model\nThe returned data content is similar for async and sync requests. When downloading the results of an async batch request, if the batch has finished processing, the response body contains the batch response. This batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests`i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item in `batchItems` contains `statusCode` and `response` fields. Each `response` in `batchItems` is of one of the following types:\n\n - [`RouteDirectionsResponse`](https://docs.microsoft.com/en-us/rest/api/maps/route/getroutedirections#routedirectionsresponse) - If the query completed successfully.\n\n - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.\n\n\nHere's a sample Batch Response with 1 _successful_ and 1 _failed_ result:\n\n\n```json\n{\n \"summary\": {\n \"successfulRequests\": 1,\n \"totalRequests\": 2\n },\n \"batchItems\": [\n {\n \"statusCode\": 200,\n \"response\": {\n \"routes\": [\n {\n \"summary\": {\n \"lengthInMeters\": 1758,\n \"travelTimeInSeconds\": 387,\n \"trafficDelayInSeconds\": 0,\n \"departureTime\": \"2018-07-17T00:49:56+00:00\",\n \"arrivalTime\": \"2018-07-17T00:56:22+00:00\"\n },\n \"legs\": [\n {\n \"summary\": {\n \"lengthInMeters\": 1758,\n \"travelTimeInSeconds\": 387,\n \"trafficDelayInSeconds\": 0,\n \"departureTime\": \"2018-07-17T00:49:56+00:00\",\n \"arrivalTime\": \"2018-07-17T00:56:22+00:00\"\n },\n \"points\": [\n {\n \"latitude\": 47.62094,\n \"longitude\": -122.34892\n },\n {\n \"latitude\": 47.62094,\n \"longitude\": -122.3485\n },\n {\n \"latitude\": 47.62095,\n \"longitude\": -122.3476\n }\n ]\n }\n ],\n \"sections\": [\n {\n \"startPointIndex\": 0,\n \"endPointIndex\": 40,\n \"sectionType\": \"TRAVEL_MODE\",\n \"travelMode\": \"bicycle\"\n }\n ]\n }\n ]\n }\n },\n {\n \"statusCode\": 400,\n \"response\":\n {\n \"error\":\n {\n \"code\": \"400 BadRequest\",\n \"message\": \"Bad request: one or more parameters were incorrectly specified or are mutually exclusive.\"\n }\n }\n }\n ]\n}\n```",
"operationId": "Route_PostRouteDirectionsBatch",
"x-ms-long-running-operation": true,
"x-ms-long-running-operation-options": {
Expand Down
Loading