Skip to content

Commit ee6f8fb

Browse files
PMEds28PMEds28
authored
Merge pull request #109402 from anastasia-ms/atlas
IndoorMaps
2 parents f921d73 + 12cae0b commit ee6f8fb

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+2196
-11
lines changed

‎articles/azure-maps/creator-indoor-maps.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: Work with indoor maps in Azure Maps Creator
3+
description: This article introduces concepts that apply to Azure Maps Creator services.
4+
author: anastasia-ms
5+
ms.author: v-stharr
6+
ms.date: 05/18/2020
7+
ms.topic: conceptual
8+
ms.service: azure-maps
9+
services: azure-maps
10+
manager: philmea
11+
---
12+
13+
14+
# Creator for indoor maps
15+
16+
This article introduces concepts and tools that apply to Azure Maps Creator. We recommend that you read this article before you begin to use the Azure Maps Creator API and SDK.
17+
18+
You can use Creator to develop applications with map features based on indoor map data. This article describes the process of uploading, converting, creating, and using your map data. The entire workflow is illustrated in the diagram below.
19+
20+
![Creator map data workflow](./media/creator-indoor-maps/workflow.png)
21+
22+
## Create Azure Maps Creator
23+
24+
To use Creator services, Azure Maps Creator must be created in an Azure Maps account. For information on how to create Azure Maps Creator in Azure Maps, see [Manage Azure Maps Creator](how-to-manage-creator.md).
25+
26+
## Upload a Drawing package
27+
28+
Creator collects indoor map data by converting an uploaded Drawing package. The Drawing package represents a constructed or remodeled facility. For information on Drawing package requirements, see [Drawing package requirements](drawing-requirements.md).
29+
30+
Use the [Azure Maps Data Upload API](https://docs.microsoft.com/rest/api/maps/data/uploadpreview) to upload a Drawing package. Upon a successful upload, the Data Upload API will return a user data identifier (`udid`). The `udid` will be used in the next step to convert the uploaded package into indoor map data.
31+
32+
## Convert a Drawing package
33+
34+
The [Azure Maps Conversion service](https://docs.microsoft.com/rest/api/maps/data/conversion) converts an uploaded Drawing package into indoor map data. The Conversion service also validates the package. Validation issues are classified into two types: errors and warnings. If any errors are detected, the conversion process fails. Should warnings be detected, the conversion will succeed. However, it’s recommended that you review and resolve all warnings. A warning means that part of the conversion was ignored or automatically fixed. Failing to resolve the warnings could result in errors in latter processes. For more information, see [Drawing package warnings and errors](drawing-conversion-error-codes.md).
35+
36+
When an error occurs, the Conversion service provides a link to the [Azure Maps Drawing Error Visualizer](drawing-error-visualizer.md) stand-alone web application. You can use the Drawing Error Visualizer to inspect [Drawing package warnings and errors](drawing-conversion-error-codes.md) that occurred during the conversion process. Once you have fixed the errors, you can then attempt to upload and convert the package.
37+
38+
## Create indoor map data
39+
40+
Azure Maps Creator provides three services:
41+
42+
* [Dataset service](https://docs.microsoft.com/rest/api/maps/dataset/createpreview).
43+
Use the Dataset service to create a dataset from a converted Drawing package data.
44+
* [Tileset service](https://docs.microsoft.com/rest/api/maps/tileset/createpreview).
45+
Use the Tileset service to create a vector-based representation of a dataset. Applications can use a tileset to present a visual tile-based view of the dataset.
46+
* [Feature State service](https://docs.microsoft.com/rest/api/maps/featurestate).Use the Feature State service to support dynamic map styling. Dynamic map styling allows applications to reflect real-time events on spaces provided by IoT system.
47+
48+
### Datasets
49+
50+
A dataset is a collection of indoor map features. The indoor map features represent facilities defined in a converted Drawing package. After creating a dataset with the [Dataset service](https://docs.microsoft.com/rest/api/maps/dataset/createpreview), you can create any number of [tilesets](#tilesets) or [feature statesets](#feature-statesets).
51+
52+
The [Dataset service](https://docs.microsoft.com/rest/api/maps/dataset/createpreview) allows developers, at any time, to add or remove facilities to an existing dataset. For more information on how to update an existing dataset using the API, see the append options in [Dataset service](https://docs.microsoft.com/rest/api/maps/dataset/createpreview). For an example of how to update a dataset, see [Data Maintenance](#data-maintenance).
53+
54+
### Tilesets
55+
56+
A tileset is a collection of vector data that represents a set of uniform grid tiles. Developers can use the [Tileset service](https://docs.microsoft.com/rest/api/maps/tileset/createpreview) to create tilesets from a dataset.
57+
58+
To reflect different content stages, you can create multiple tilesets from the same dataset. For example, you could make one tileset with furniture and equipment, and another tileset without furniture and equipment. You might choose to generate one tileset with the most recent data updates, and one without the most recent data updates.
59+
60+
In addition to the vector data, the tileset provides metadata for map rendering optimization. For example, tileset metadata contains a min and max zoom level for the tileset. The metadata also provides a bounding box defining the geographic extent of the tileset. The bounding box allows an application to programmatically set the correct center point. For more information about tileset metadata, see [Tileset List API](https://docs.microsoft.com/rest/api/maps/tileset/listpreview).
61+
62+
Once a tileset has been created, it can be retrieved by the [Render V2 service](#render-v2-service).
63+
64+
If a tileset becomes outdated and is no longer useful, you can delete the tileset. For more information on how to delete tilesets, see [Data Maintenance](#data-maintenance).
65+
66+
>[!NOTE]
67+
>A tileset is independent of the dataset from which it was created. If you create tilesets from a dataset, and then subsequently update that dataset, the tilesets will not be updated. To reflect changes in a dataset, you must create new tilesets. Similarly, if you delete a tileset, the dataset will not be affected.
68+
69+
### Feature statesets
70+
71+
Feature statesets are collections of dynamic properties (*states*) assigned to dataset features such as rooms or equipment. An example of a *state* could be temperature or occupancy. Each *state* is a key/value pair containing the name of the property, the value, and the timestamp of the last update.
72+
73+
The [Feature State service](https://docs.microsoft.com/rest/api/maps/featurestate/createstatesetpreview) lets you create and manage a feature stateset for a dataset. The stateset is defined by one or more *states*. Each feature, such as a room, can have one *state* attached to it.
74+
75+
The value of each *state* in a stateset can be updated or retrieved by IoT devices or other applications. For example, using the [Feature State Update API](https://docs.microsoft.com/rest/api/maps/featurestate/updatestatespreview), devices measuring space occupancy can systematically post the state change of a room.
76+
77+
An application can use a feature stateset to dynamically render features in a facility according to their current state and respective map style. For more information on using feature statesets to style features in a rendering map, see [Indoor Web SDK Module](#indoor-maps-module).
78+
79+
>[!NOTE]
80+
>Like tilesets, changing a dataset does not affect the existing feature stateset and deleting a feature stateset will have no effect on the dataset to which it is attached.
81+
82+
## Using indoor maps
83+
84+
### Render V2 service
85+
86+
The Azure Maps [Render V2 service-Get Map Tile API](https://docs.microsoft.com/rest/api/maps/renderv2/getmaptilepreview) has been extended to support Creator tilesets.
87+
88+
[Render V2 service-Get Map State Tile API](https://docs.microsoft.com/rest/api/maps/renderv2/getmaptilepreview) allows applications to request tilesets. The tilesets can then be integrated into a map control or SDK. For an example of a map control that uses the Render V2 service, see [Indoor Maps Module](#indoor-maps-module).
89+
90+
### Web Feature Service API
91+
92+
Datasets can be queried using the [Web Feature Service (WFS) API](https://docs.microsoft.com/rest/api/maps/wfs). WFS follows the [Open Geospatial Consortium API Features](http://docs.opengeospatial.org/DRAFTS/17-069r1.html). The WFS API lets you query features within the dataset itself. For example, you can use WFS to find all mid-size meeting rooms of a given facility and floor level.
93+
94+
### Indoor Maps module
95+
96+
The [Azure Maps Web SDK](https://docs.microsoft.com/azure/azure-maps/) includes the Indoor Maps module. This module offers extended functionalities to the Azure Maps *Map Control* library. The Indoor Maps module renders indoor maps created in Creator. It integrates widgets such as *floor picker*, which helps users visualize the different floors.
97+
98+
The Indoor Maps module allows you to create web applications that integrate indoor map data with other [Azure Maps services](https://docs.microsoft.com/azure/azure-maps/). The most common application setups could include adding knowledge to indoor maps from other maps such as road, imagery, weather, and transit.
99+
100+
The Indoor Maps module also supports dynamic map styling. For a step-by-step walk-through on how to implement feature stateset dynamic styling in an application, see [How to Use the Indoor Map Module](how-to-use-indoor-module.md)
101+
102+
### Azure Maps integration
103+
104+
As you begin to develop solutions for indoor maps, you can discover ways to integrate existing Azure Maps capabilities. For example, asset tracking or safety scenarios could be implemented by using the [Azure Maps Geofence API](https://docs.microsoft.com/rest/api/maps/spatial/postgeofence) with Creator indoor maps. The Geofence API could be used to determine, for example, whether a worker enters or leaves specific indoor areas. For more information on how to connect Azure Maps with IoT telemetry is available [here](tutorial-iot-hub-maps.md).
105+
106+
### Data Maintenance
107+
108+
Azure Maps Creator List, Update, and Delete API allows you to list, update, and delete your datasets, tilesets, and feature statesets.
109+
110+
>[!NOTE]
111+
>Whenever you review a list of items and decide to delete them, you must consider the impact of that deletion on all dependent API or applications. For example, if you should delete a tileset that is currently being used by an application by means of the [Render V2 - Get Map Tile API](https://docs.microsoft.com/rest/api/maps/renderv2/getmaptilepreview), deleting that tileset would result in an application failure to render that tileset.
112+
113+
### Example: Updating a dataset
114+
115+
The following example shows you how to update a dataset, create a new tileset, and delete an old tileset.
116+
117+
1. Follow steps in the [Upload a Drawing package](#upload-a-drawing-package) and [Convert a Drawing package](#convert-a-drawing-package) sections to upload and convert the new Drawing package.
118+
119+
2. Use the [Dataset Create API](https://docs.microsoft.com/rest/api/maps/dataset/createpreview) to append the converted data to the existing dataset.
120+
121+
3. Use the [Tileset Create API](https://docs.microsoft.com/rest/api/maps/tileset/createpreview) to generate a new tileset out of the updated dataset. Save the new tilesetId for step 4.
122+
123+
4. Update the tileset identifier in your application to enable the visualization of the updated campus dataset. If the old tileset is no longer in use, you can delete it.
124+
125+
## Next steps
126+
127+
> [!div class="nextstepaction"]
128+
> [Tutorial: Creating a Creator indoor map](tutorial-creator-indoor-maps.md)

‎articles/azure-maps/creator-long-running-operation.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: Azure Maps Long-Running Operation API
3+
description: Learn about long-running asynchronous background processing in Azure Maps
4+
author: anastasia-ms
5+
ms.author: v-stharr
6+
ms.date: 05/18/2020
7+
ms.topic: conceptual
8+
ms.service: azure-maps
9+
services: azure-maps
10+
manager: philmea
11+
ms.custom: mvc
12+
---
13+
14+
# Creator Long-Running Operation API
15+
16+
Some API in Azure Maps use an [Asynchronous Request-Reply pattern](https://docs.microsoft.com/azure/architecture/patterns/async-request-reply). This pattern allows Azure Maps to provide highly available and responsive services. This article explains Azure Map's specific implementation of long-running asynchronous background processing.
17+
18+
## Submitting a request
19+
20+
A client application starts a long-running operation through a synchronous call to an HTTP API. Typically, this call is in the form of an HTTP POST request. When an asynchronous workload is successfully created, the API will return an HTTP `202` status code, indicating that the request has been accepted. This response contains a `Location` header pointing to an endpoint that the client can poll to check the status of the long-running operation.
21+
22+
### Example of a success response
23+
24+
```HTTP
25+
Status: 202 Accepted
26+
Location: https://atlas.microsoft.com/service/operations/{operationId}
27+
28+
```
29+
30+
If the call doesn't pass validation, the API will instead return an HTTP `400` response for a Bad Request. The response body will provide the client more information on why the request was invalid.
31+
32+
### Monitoring the operation status
33+
34+
The location endpoint provided in the accepted response headers can be polled to check the status of the long-running operation. The response body from operation status request will always contain the `status` and the `createdDateTime` properties. The `status` property shows the current state of the long-running operation. Possible states include `"NotStarted"`, `"Running"`, `"Succeeded"`, and `"Failed"`. The `createdDateTime` property shows the time the initial request was made to start the long-running operation. When the state is either `"NotStarted"` or `"Running"`, a `Retry-After` header will also be provided with the response. The `Retry-After` header, measured in seconds, can be used to determine when the next polling call to the operation status API should be made.
35+
36+
### Example of running a status response
37+
38+
```HTTP
39+
Status: 200 OK
40+
Retry-After: 30
41+
{
42+
"operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
43+
"createdDateTime": "3/11/2020 8:45:13 PM +00:00",
44+
"status": "Running"
45+
}
46+
```
47+
48+
## Handling operation completion
49+
50+
Upon completing the long-running operation, the status of the response will either be `"Succeeded"` or `"Failed"`. When a new resource has been created from a long-running operation, the success response will return an HTTP `201 Created` status code. The response will also contain a `Location` header that points to metadata about the resource. When no new resource has been created, the success response will return an HTTP `200 OK` status code. Upon a failure, the response status code will also be the `200 OK`code. However, the response will have an `error` property in the body. The error data adheres to the OData error specification.
51+
52+
### Example of success response
53+
54+
```HTTP
55+
Status: 201 Created
56+
Location: "https://atlas.microsoft.com/tileset/{tileset-id}"
57+
{
58+
"operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
59+
"createdDateTime": "3/11/2020 8:45:13 PM +00:00",
60+
"status": "Succeeded",
61+
"resourceLocation": "https://atlas.microsoft.com/tileset/{tileset-id}"
62+
}
63+
```
64+
65+
### Example of failure response
66+
67+
```HTTP
68+
Status: 200 OK
69+
70+
{
71+
"operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
72+
"createdDateTime": "3/11/2020 8:45:13 PM +00:00",
73+
"status": "Failed",
74+
"error": {
75+
"code": "InvalidFeature",
76+
"message": "The provided feature is invalid.",
77+
"details": {
78+
"code": "NoGeometry",
79+
"message": "No geometry was provided with the feature."
80+
}
81+
}
82+
}
83+
```

0 commit comments

Comments
 (0)