Dataset - Create

  • Reference
Service:
Maps Creator
API Version:
2.0

Applies to: see pricing tiers.

Creator makes it possible to develop applications based on your private indoor map data using Azure Maps API and SDK. This article introduces concepts and tools that apply to Azure Maps Creator.

This API allows the caller to create a dataset from data that was uploaded to the Azure Maps Data Service and converted using the Azure Maps Conversion Service.

You can use this API in a scenario like uploading a DWG zip package for a building, converting the zip package using the Azure Maps Conversion Service, and creating a dataset from the converted zip package. The created dataset can be used to create tilesets using the Azure Maps Tileset Service and can be queried via the Azure Maps WFS Service.

Submit Create Request

To create your dataset, you will use a POST request where the conversionId query parameter is an ID that represents the converted DWG zip package, the datasetId parameter will be the ID of a previously created dataset to append with the current dataset and, optionally, the description query parameter will contain a description (if description is not provided a default description will be given).

The Create API is a long-running request.

POST https://{geography}.atlas.microsoft.com/datasets?api-version=2.0&conversionId={conversionId}
With optional parameters: 
POST https://{geography}.atlas.microsoft.com/datasets?api-version=2.0&conversionId={conversionId}&datasetId={datasetId}&description={description}

URI Parameters

Name In Required Type Description
geography
 path True
  • string

This parameter specifies where the Azure Maps Creator resource is located. Valid values are us and eu.
api-version
 query True
  • string

Version number of Azure Maps API.
conversionId
 query True
  • string

The unique ID used to create the dataset. The conversionId must have been obtained from a successful call to the Conversion Service Convert API and may be provided with multiple query parameters with same name (if more than one is provided).
datasetId
 query
  • string

The ID for the dataset to append with. The dataset must originate from a previous dataset creation call that matches the datasetId
description
 query
  • string

The description to be given to the dataset.

Request Header

Name Required Type Description
x-ms-client-id
  • string

Specifies which account is intended for usage in conjunction with the Azure AD security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Azure AD security in Azure Maps see the following articles for guidance.

Responses

Name Type Description
200 OK

The operation is running or complete. If the operation was successful, use the Resource-Location header to obtain the path to the result.

Headers

  • Resource-Location: string
202 Accepted

Request Accepted: The request has been accepted for processing. Please use the URL in the Operation-Location Header to obtain status.

Headers

  • Operation-Location: string
Other Status Codes

An unexpected error occurred.

Security

AADToken

These are the Azure Active Directory OAuth2 Flows. When paired with Azure role-based access 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.

To implement scenarios, we recommend viewing authentication concepts. In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.

Notes

  • 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.

The Authorization URL is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. * The Azure role-based access control is configured from the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs. * Usage of the Azure Maps Web SDK allows for configuration based setup of an application for multiple use cases.

  • Currently, Azure Active Directory v1.0 or v2.0 supports Work, School, and Guests but does not support Personal accounts.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
https://atlas.microsoft.com/.default https://atlas.microsoft.com/.default

subscription-key

This is a shared key that is provisioned when creating an Azure Maps resource through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.

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.

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.

Type: apiKey
In: query

SAS Token

This is a shared access signature token is created from the List SAS operation on the Azure Maps resource through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.

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.

For publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the Map account resource to limit rendering abuse and regularly renew the SAS Token.

Type: apiKey
In: header

Examples

Create dataset from a converted CAD file provided by conversionId

Sample Request

POST https://us.atlas.microsoft.com/datasets?api-version=2.0&conversionId=[conversionId]

Sample Response

Status code:
200 
Resource-Location: https://us.atlas.microsoft.com/mapData/3e36b996-f6d1-b068-0fcb-dd6b014c3447?api-version=2.0
Response Body
{
  "operationId": "8b1288fa-1958-4a2b-b68e-13a7i5af7d7c",
  "created": "2021-04-20T22:43:14.9401559+00:00",
  "status": "Succeeded"
}
Status code:
202 
Operation-Location: https://us.atlas.microsoft.com/datasets/operations/{operationId}?api-version=2.0
Access-Control-Expose-Headers: Operation-Location

Definitions

ErrorAdditionalInfo

The resource management error additional info.
ErrorDetail

The error detail.
ErrorResponse

Error response
LongRunningOperationResult

The response model for a Long-Running Operations API.
LroStatus

The status state of the request.

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info
  • object

The additional info.
type
  • string

The additional info type.

ErrorDetail

The error detail.

Name Type Description
additionalInfo

The error additional info.
code
  • string

The error code.
details

The error details.
message
  • string

The error message.
target
  • string

The error target.

ErrorResponse

Error response

Name Type Description
error

The error object.

LongRunningOperationResult

The response model for a Long-Running Operations API.

Name Type Description
created
  • string

The created timestamp.
error

The error detail.
operationId
  • string

The Id for this long-running operation.
status

The status state of the request.
warning

The error detail.

LroStatus

The status state of the request.

Name Type Description
Failed
  • string

The request has one or more failures.
NotStarted
  • string

The request has not started processing yet.
Running
  • string

The request has started processing.
Succeeded
  • string

The request has successfully completed.