|
| 1 | +{ |
| 2 | + "swagger": "2.0", |
| 3 | + "info": { |
| 4 | + "title": "Azure Maps Asynchronous Batch Management Service", |
| 5 | + "version": "2024-04-01-preview", |
| 6 | + "description": "Azure Maps Asynchronous Batch Management REST APIs" |
| 7 | + }, |
| 8 | + "x-ms-parameterized-host": { |
| 9 | + "hostTemplate": "{geography}.atlas.microsoft.com", |
| 10 | + "parameters": [ |
| 11 | + { |
| 12 | + "$ref": "../../../Common/stable/2023-06-01/common.json#/parameters/GeographicResourceLocation" |
| 13 | + } |
| 14 | + ] |
| 15 | + }, |
| 16 | + "schemes": [ |
| 17 | + "https" |
| 18 | + ], |
| 19 | + "consumes": [], |
| 20 | + "produces": [ |
| 21 | + "application/json" |
| 22 | + ], |
| 23 | + "securityDefinitions": { |
| 24 | + "AADToken": { |
| 25 | + "type": "oauth2", |
| 26 | + "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", |
| 27 | + "flow": "implicit", |
| 28 | + "description": "These are the [Microsoft Entra OAuth 2.0](/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n> [!NOTE]\n> * This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n> * The `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Microsoft Entra ID configurations. \n> * The Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n> * Usage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n> * For more information on Microsoft identity platform, see [Microsoft identity platform overview](/entra/identity-platform/v2-overview).\n\n", |
| 29 | + "scopes": { |
| 30 | + "https://atlas.microsoft.com/.default": "https://atlas.microsoft.com/.default" |
| 31 | + } |
| 32 | + }, |
| 33 | + "AzureKey": { |
| 34 | + "type": "apiKey", |
| 35 | + "description": "This is a shared key that is provisioned when creating an [Azure Maps resource](https://aka.ms/amauth) through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n\n With this key, any application is authorized to access all REST APIs. In other words, these can currently be treated as master keys to the account which they are issued for.\n\n For publicly exposed applications, our recommendation is to use server-to-server access of Azure Maps REST APIs where this key can be securely stored.", |
| 36 | + "name": "subscription-key", |
| 37 | + "in": "header" |
| 38 | + }, |
| 39 | + "SasToken": { |
| 40 | + "type": "apiKey", |
| 41 | + "description": "This is a shared access signature token is created from the List SAS operation on the [Azure Maps resource](https://aka.ms/amauth) through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n\n With this token, any application is authorized to access with Azure role-based access controls and fine-grain control to the expiration, rate, and region(s) of use for the particular token. In other words, the SAS Token can be used to allow applications to control access in a more secured way than the shared key.\n\n For publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the [Map account resource](https://aka.ms/amauth) to limit rendering abuse and regularly renew the SAS Token.", |
| 42 | + "name": "SAS Token", |
| 43 | + "in": "header" |
| 44 | + } |
| 45 | + }, |
| 46 | + "security": [ |
| 47 | + { |
| 48 | + "AADToken": [ |
| 49 | + "https://atlas.microsoft.com/.default" |
| 50 | + ] |
| 51 | + }, |
| 52 | + { |
| 53 | + "AzureKey": [] |
| 54 | + }, |
| 55 | + { |
| 56 | + "SasToken": [] |
| 57 | + } |
| 58 | + ], |
| 59 | + "responses": {}, |
| 60 | + "parameters": { |
| 61 | + "ApiVersion": { |
| 62 | + "name": "api-version", |
| 63 | + "description": "Version number of Azure Maps API.", |
| 64 | + "type": "string", |
| 65 | + "in": "query", |
| 66 | + "required": true, |
| 67 | + "x-ms-parameter-location": "client" |
| 68 | + }, |
| 69 | + "OperationId": { |
| 70 | + "name": "operationId", |
| 71 | + "description": "System generated unique identifier for the asynchronous batch operation after it has been submitted.", |
| 72 | + "type": "string", |
| 73 | + "format": "uuid", |
| 74 | + "maxLength": 36, |
| 75 | + "minLength": 36, |
| 76 | + "pattern": "^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$", |
| 77 | + "in": "path", |
| 78 | + "required": true |
| 79 | + } |
| 80 | + }, |
| 81 | + "paths": { |
| 82 | + "/asyncBatch/operations/{operationId}": { |
| 83 | + "get": { |
| 84 | + "description": "Get the status of an asynchronous batch operation by its operation ID.", |
| 85 | + "operationId": "AsynchronousBatchManagement_GetOperation", |
| 86 | + "produces": [ |
| 87 | + "application/json" |
| 88 | + ], |
| 89 | + "x-ms-examples": { |
| 90 | + "Get a not started operation status": { |
| 91 | + "$ref": "./examples/GetOperationStatusNotStarted.json" |
| 92 | + }, |
| 93 | + "Get a running operation status": { |
| 94 | + "$ref": "./examples/GetOperationStatusRunning.json" |
| 95 | + }, |
| 96 | + "Get a succeeded operation status": { |
| 97 | + "$ref": "./examples/GetOperationStatusSucceeded.json" |
| 98 | + }, |
| 99 | + "Get a failed operation status": { |
| 100 | + "$ref": "./examples/GetOperationStatusFailed.json" |
| 101 | + } |
| 102 | + }, |
| 103 | + "parameters": [ |
| 104 | + { |
| 105 | + "$ref": "#/parameters/ApiVersion" |
| 106 | + }, |
| 107 | + { |
| 108 | + "$ref": "#/parameters/OperationId" |
| 109 | + } |
| 110 | + ], |
| 111 | + "responses": { |
| 112 | + "200": { |
| 113 | + "description": "OK", |
| 114 | + "schema": { |
| 115 | + "$ref": "#/definitions/AsyncBatchOperation" |
| 116 | + } |
| 117 | + }, |
| 118 | + "default": { |
| 119 | + "description": "An unexpected error occurred.", |
| 120 | + "schema": { |
| 121 | + "$ref": "../../../../../common-types/data-plane/v1/types.json#/definitions/ErrorResponse" |
| 122 | + }, |
| 123 | + "headers": { |
| 124 | + "x-ms-error-code": { |
| 125 | + "type": "string", |
| 126 | + "description": "Error code of the error that occurred." |
| 127 | + } |
| 128 | + }, |
| 129 | + "x-ms-error-response": true |
| 130 | + } |
| 131 | + } |
| 132 | + } |
| 133 | + }, |
| 134 | + "/asyncBatch/operations": { |
| 135 | + "get": { |
| 136 | + "description": "List the status of all asynchronous batch operations available to the user.", |
| 137 | + "operationId": "AsynchronousBatchManagement_ListAllOperations", |
| 138 | + "x-ms-examples": { |
| 139 | + "Get operations with various status": { |
| 140 | + "$ref": "./examples/GetOperations.json" |
| 141 | + } |
| 142 | + }, |
| 143 | + "parameters": [ |
| 144 | + { |
| 145 | + "$ref": "../../../Common/stable/2023-06-01/common.json#/parameters/ClientId" |
| 146 | + }, |
| 147 | + { |
| 148 | + "$ref": "#/parameters/ApiVersion" |
| 149 | + } |
| 150 | + ], |
| 151 | + "responses": { |
| 152 | + "200": { |
| 153 | + "description": "OK", |
| 154 | + "schema": { |
| 155 | + "$ref": "#/definitions/AsyncBatchOperationsList" |
| 156 | + } |
| 157 | + }, |
| 158 | + "default": { |
| 159 | + "description": "An unexpected error occurred.", |
| 160 | + "schema": { |
| 161 | + "$ref": "../../../../../common-types/data-plane/v1/types.json#/definitions/ErrorResponse" |
| 162 | + }, |
| 163 | + "headers": { |
| 164 | + "x-ms-error-code": { |
| 165 | + "type": "string", |
| 166 | + "description": "Error code of the error that occurred." |
| 167 | + } |
| 168 | + }, |
| 169 | + "x-ms-error-response": true |
| 170 | + } |
| 171 | + }, |
| 172 | + "x-ms-pageable": { |
| 173 | + "nextLinkName": "nextLink" |
| 174 | + } |
| 175 | + } |
| 176 | + } |
| 177 | + }, |
| 178 | + "definitions": { |
| 179 | + "AsyncBatchOperationResult": { |
| 180 | + "type": "object", |
| 181 | + "description": "The result of the asynchronous batch operation.", |
| 182 | + "properties": { |
| 183 | + "outputBlobUrl": { |
| 184 | + "type": "string", |
| 185 | + "format": "uri", |
| 186 | + "description": "URL to the output blob containing the batch results." |
| 187 | + } |
| 188 | + }, |
| 189 | + "required": [ |
| 190 | + "outputBlobUrl" |
| 191 | + ] |
| 192 | + }, |
| 193 | + "AsyncBatchOperation": { |
| 194 | + "type": "object", |
| 195 | + "description": "This object is returned from a successful Get Operation request.", |
| 196 | + "properties": { |
| 197 | + "operationId": { |
| 198 | + "description": "Unique identifier for the asynchronous batch operation.", |
| 199 | + "type": "string" |
| 200 | + }, |
| 201 | + "operationType": { |
| 202 | + "type": "string", |
| 203 | + "description": "Type of asynchronous batch operation", |
| 204 | + "enum": [ |
| 205 | + "Geocode", |
| 206 | + "ReverseGeocode", |
| 207 | + "RouteDirections" |
| 208 | + ], |
| 209 | + "x-ms-enum": { |
| 210 | + "name": "OperationTypeEnum", |
| 211 | + "modelAsString": true, |
| 212 | + "values": [ |
| 213 | + { |
| 214 | + "value": "Geocode", |
| 215 | + "description": "Forward geocode asynchronous batch job." |
| 216 | + }, |
| 217 | + { |
| 218 | + "value": "ReverseGeocode", |
| 219 | + "description": "Reverse geocode asynchronous batch job." |
| 220 | + }, |
| 221 | + { |
| 222 | + "value": "RouteDirections", |
| 223 | + "description": "Route directions asynchronous batch job." |
| 224 | + } |
| 225 | + ] |
| 226 | + } |
| 227 | + }, |
| 228 | + "inputBlobUrl": { |
| 229 | + "description": "The URL to the input blob containing the batch of queries. This should be a valid URL pointing to a blob of an Azure Storage Account", |
| 230 | + "type": "string", |
| 231 | + "format": "uri" |
| 232 | + }, |
| 233 | + "outputStorageUrl": { |
| 234 | + "description": "The URL that points to a blob storage where the batch results will be stored.", |
| 235 | + "type": "string", |
| 236 | + "format": "uri" |
| 237 | + }, |
| 238 | + "msiClientId": { |
| 239 | + "type": "string", |
| 240 | + "description": "Client ID of a user-assigned managed identity. This is used for authentication and authorization purposes. If the managed identity is system-assigned, this field can be null." |
| 241 | + }, |
| 242 | + "createdDateTime": { |
| 243 | + "type": "string", |
| 244 | + "format": "date-time", |
| 245 | + "description": "Timestamp when the operation was created." |
| 246 | + }, |
| 247 | + "lastActionDateTime": { |
| 248 | + "type": "string", |
| 249 | + "format": "date-time", |
| 250 | + "description": "Timestamp when the operation status was updated." |
| 251 | + }, |
| 252 | + "percentComplete": { |
| 253 | + "type": "integer", |
| 254 | + "format": "int32", |
| 255 | + "description": "Percentage indicating the completion status of the operation." |
| 256 | + }, |
| 257 | + "totalItemCount": { |
| 258 | + "type": "integer", |
| 259 | + "format": "int32", |
| 260 | + "description": "Total number of items in the batch operation." |
| 261 | + }, |
| 262 | + "status": { |
| 263 | + "type": "string", |
| 264 | + "description": "Current status of the batch operation.", |
| 265 | + "enum": [ |
| 266 | + "NotStarted", |
| 267 | + "Running", |
| 268 | + "Succeeded", |
| 269 | + "Failed", |
| 270 | + "Canceled" |
| 271 | + ], |
| 272 | + "x-ms-enum": { |
| 273 | + "name": "StatusEnum", |
| 274 | + "modelAsString": true, |
| 275 | + "values": [ |
| 276 | + { |
| 277 | + "value": "NotStarted", |
| 278 | + "description": "The operation has not started yet." |
| 279 | + }, |
| 280 | + { |
| 281 | + "value": "Running", |
| 282 | + "description": "The operation is running." |
| 283 | + }, |
| 284 | + { |
| 285 | + "value": "Succeeded", |
| 286 | + "description": "The operation has completed successfully." |
| 287 | + }, |
| 288 | + { |
| 289 | + "value": "Failed", |
| 290 | + "description": "The operation has failed." |
| 291 | + }, |
| 292 | + { |
| 293 | + "value": "Canceled", |
| 294 | + "description": "The operation has been canceled." |
| 295 | + } |
| 296 | + ] |
| 297 | + } |
| 298 | + }, |
| 299 | + "result": { |
| 300 | + "$ref": "#/definitions/AsyncBatchOperationResult" |
| 301 | + }, |
| 302 | + "error": { |
| 303 | + "type": "object", |
| 304 | + "description": "The error detail.", |
| 305 | + "properties": { |
| 306 | + "code": { |
| 307 | + "readOnly": true, |
| 308 | + "type": "string", |
| 309 | + "description": "The error code." |
| 310 | + }, |
| 311 | + "message": { |
| 312 | + "readOnly": true, |
| 313 | + "type": "string", |
| 314 | + "description": "The error message." |
| 315 | + } |
| 316 | + } |
| 317 | + } |
| 318 | + }, |
| 319 | + "required": [ |
| 320 | + "operationId", |
| 321 | + "operationType", |
| 322 | + "inputBlobUrl", |
| 323 | + "outputStorageUrl", |
| 324 | + "createdDateTime", |
| 325 | + "lastActionDateTime", |
| 326 | + "percentComplete", |
| 327 | + "totalItemCount", |
| 328 | + "status" |
| 329 | + ] |
| 330 | + }, |
| 331 | + "AsyncBatchOperationsList": { |
| 332 | + "description": "This object is returned from a successful Get Specific Operations request.", |
| 333 | + "type": "object", |
| 334 | + "properties": { |
| 335 | + "value": { |
| 336 | + "description": "Array containing the details of operations", |
| 337 | + "type": "array", |
| 338 | + "items": { |
| 339 | + "$ref": "#/definitions/AsyncBatchOperation" |
| 340 | + } |
| 341 | + }, |
| 342 | + "nextLink": { |
| 343 | + "type": "string", |
| 344 | + "format": "uri", |
| 345 | + "description": "The is the link to the next page of the features returned. If it's the last page, this is null." |
| 346 | + } |
| 347 | + }, |
| 348 | + "required": [ |
| 349 | + "value" |
| 350 | + ] |
| 351 | + } |
| 352 | + } |
| 353 | +} |
0 commit comments