Merge pull request #265613 from stevemunk/tutorial-geofence-update-2

Replacing references to the dataRegistry service with the data service

Author: prmerger-automator[bot]

articles/azure-maps/tutorial-geofence.md

@@ -3,7 +3,7 @@ title: 'Tutorial: Create a geofence and track devices on a Microsoft Azure Map'
 description: Tutorial on how to set up a geofence. See how to track devices relative to the geofence by using the Azure Maps Spatial service
 author: eriklindeman
 ms.author: eriklind
-ms.date: 09/14/2023
+ms.date: 02/07/2024
 ms.topic: tutorial
 ms.service: azure-maps
 services: azure-maps
@@ -21,11 +21,11 @@ Consider the following scenario:
 Azure Maps provides services to support the tracking of equipment entering and exiting the construction area. In this tutorial, you will:
 
 > [!div class="checklist"]
->
-> * Upload [Geofencing GeoJSON data] that defines the construction site areas you want to monitor. You'll upload geofences as polygon coordinates to your Azure storage account, then use the [data registry] service to register that data with your Azure Maps account.
+> <!-- > * Upload [Geofencing GeoJSON data] that defines the construction site areas you want to monitor. You'll upload geofences as polygon coordinates to your Azure storage account, then use the [data registry] service to register that data with your Azure Maps account.   --->
+> * Upload [Geofencing GeoJSON data] that defines the construction site areas you want to monitor.  You'll use the [Data Upload API] to upload geofences as polygon coordinates to your Azure Maps account.
 > * Set up two [logic apps] that, when triggered, send email notifications to the construction site operations manager when equipment enters and exits the geofence area.
 > * Use [Azure Event Grid] to subscribe to enter and exit events for your Azure Maps geofence. You set up two webhook event subscriptions that call the HTTP endpoints defined in your two logic apps. The logic apps then send the appropriate email notifications of equipment moving beyond or entering the geofence.
-> * Use [Search Geofence Get API] to receive notifications when a piece of equipment exits and enters the geofence areas.
+> * Use [Spatial Geofence Get API] to receive notifications when a piece of equipment exits and enters the geofence areas.
 
 ## Prerequisites
 
@@ -39,11 +39,47 @@ This tutorial uses the [Postman] application, but you can use a different API de
 >
 > In the URL examples, replace `{Your-Azure-Maps-Subscription-key}` with your Azure Maps subscription key.
 
+## Create an Azure Maps account with a global region
+
+The Geofence API async event requires the region property of your Azure Maps account be set to ***Global***. This setting isn't given as an option when creating an Azure Maps account in the Azure portal, however you do have several other options for creating a new Azure Maps account with the *global* region setting. This section lists the three methods that can be used to create an Azure Maps account with the region set to *global*.
+
+> [!NOTE]
+> The `location` property in both the ARM template and PowerShell `New-AzMapsAccount` command refer to the same property as the `Region` field in the Azure portal.
+
 ## Upload geofencing GeoJSON data
 
 This tutorial demonstrates how to upload geofencing GeoJSON data that contains a `FeatureCollection`. The `FeatureCollection` contains two geofences that define polygonal areas within the construction site. The first geofence has no time expiration or restrictions. The second can only be queried against during business hours (9:00 AM-5:00 PM in the Pacific Time zone), and will no longer be valid after January 1, 2022. For more information on the GeoJSON format, see [Geofencing GeoJSON data].
 
-Create the geofence JSON file using the following geofence data. You'll upload this file into your Azure storage account next.
+>[!TIP]
+>You can update your geofencing data at any time. For more information, see [Data Upload API].
+To upload the geofencing GeoJSON data:
+
+1. In the Postman app, select **New**.
+
+2. In the **Create New** window, select **HTTP Request**.
+
+3. Enter a **Request name** for the request, such as *POST GeoJSON Data Upload*.
+
+4. Select the **POST** HTTP method.
+
+5. Enter the following URL. The request should look like the following URL:
+
+    ```HTTP
+    https://{geography}.atlas.microsoft.com/mapData?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2.0&dataFormat=geojson
+    ```
+
+    The `geojson` parameter in the URL path represents the data format of the data being uploaded.
+
+   > [!NOTE]
+   > Replace {geography} with your geographic scope. For more information, see [Azure Maps service geographic scope] and the [Spatial Geofence Get API].
+
+6. Select the **Body** tab.
+
+7. In the dropdown lists, select **raw** and **JSON**.
+
+8. Copy the following GeoJSON data, and then paste it in the **Body** window:
+
+<!--Create the geofence JSON file using the following geofence data. You'll upload this file into your Azure storage account next.-->
 
    ```JSON
    {
@@ -131,10 +167,79 @@ Create the geofence JSON file using the following geofence data. You'll upload t
    }
    ```
 
-Follow the steps outlined in the [How to create data registry] article to upload the geofence JSON file into your Azure storage account and register it in your Azure Maps account.
+<!--Follow the steps outlined in the [How to create data registry] article to upload the geofence JSON file into your Azure storage account and register it in your Azure Maps account.-->
+
+9. Select **Send**.
+
+10. In the response window, select the **Headers** tab.
+
+11. Copy the value of the **Operation-Location** key, which is the `status URL`. The `status URL` is used to check the status of the GeoJSON data upload.
+
+    ```http
+    https://{geography}.atlas.microsoft.com/mapData/operations/{operationId}?api-version=2.0
+    ```
+
+### Check the GeoJSON data upload status
+
+To check the status of the GeoJSON data and retrieve its unique ID (`udid`):
+
+1. Select **New**.
+
+2. In the **Create New** window, select **HTTP Request**.
+
+3. Enter a **Request name** for the request, such as *GET Data Upload Status*.
+
+4. Select the **GET** HTTP method.
+
+5. Enter the `status URL` you copied in [Upload Geofencing GeoJSON data]. The request should look like the following URL:
+
+   ```HTTP
+   https://{geography}.atlas.microsoft.com/mapData/{operationId}?api-version=2.0&subscription-key={Your-Azure-Maps-Subscription-key}
+   ```
+
+6. Select **Send**.
+
+7. In the response window, select the **Headers** tab.
+
+8. Copy the value of the **Resource-Location** key, which is the `resource location URL`. The `resource location URL` contains the unique identifier (`udid`) of the uploaded data. Save the `udid` to query the Get Geofence API in the last section of this tutorial.
+
+### (Optional) Retrieve GeoJSON data metadata
+
+You can retrieve metadata from the uploaded data. The metadata contains information like the resource location URL, creation date, updated date, size, and upload status.
+
+To retrieve content metadata:
+
+1. Select **New**.
+
+2. In the **Create New** window, select **HTTP Request**.
+
+3. Enter a **Request name** for the request, such as *GET Data Upload Metadata*.
+
+4. Select the **GET** HTTP method.
+
+5. Enter the `resource Location URL` you copied in [Check the GeoJSON data upload status]. The request should look like the following URL:
+
+    ```http
+    https://{geography}.atlas.microsoft.com/mapData/metadata/{udid}?api-version=2.0&subscription-key={Your-Azure-Maps-Subscription-key}
+    ```
+
+6. In the response window, select the **Body** tab. The metadata should look like the following JSON fragment:
 
+    ```json
+    {
+        "udid": "{udid}",
+        "location": "https://{geography}.atlas.microsoft.com/mapData/6ebf1ae1-2a66-760b-e28c-b9381fcff335?api-version=2.0",
+        "created": "5/18/2021 8:10:32 PM +00:00",
+        "updated": "5/18/2021 8:10:37 PM +00:00",
+        "sizeInBytes": 946901,
+        "uploadStatus": "Completed"
+    }
+    ```
+
+<!--
 > [!IMPORTANT]
 > Make sure to make a note of the unique identifier (`udid`) value, you will need it. The `udid` is how you reference the geofence you uploaded into your Azure storage account from your source code and HTTP requests.
+-->
 
 ## Create workflows in Azure Logic Apps
 
@@ -248,15 +353,12 @@ Each of the following sections makes API requests by using the five different lo
 
 4. Select the **GET** HTTP method.
 
-5. Enter the following URL. The request should look like the following URL (replace `{udid}` with the `udid` you saved in the [Upload Geofencing GeoJSON data section]).
+5. Enter the following URL. The request should look like the following URL (replace `{udid}` with the `udid` you saved in the [Upload Geofencing GeoJSON data] section).
 
    ```HTTP
    https://{geography}.atlas.microsoft.com/spatial/geofence/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2022-08-01&deviceId=device_01&udid={udid}&lat=47.638237&lon=-122.1324831&searchBuffer=5&isAsync=True&mode=EnterAndExit
    ```
 
-   > [!NOTE]
-   > Replace {geography} with your geographic scope. For more information, see [Azure Maps service geographic scope] and the [Spatial Geofence Get API].
-
 6. Select **Send**.
 
 7. The response should like the following GeoJSON fragment:
@@ -287,7 +389,7 @@ Each of the following sections makes API requests by using the five different lo
     }
     ```
 
-In the preceding GeoJSON response, the negative distance from the main site geofence means that the equipment is inside the geofence. The positive distance from the subsite geofence means that the equipment is outside the subsite geofence. Because this is the first time this device has been located inside the main site geofence, the `isEventPublished` parameter is set to `true`. The Operations Manager receives an email notification that equipment has entered the geofence.
+In the preceding GeoJSON response, the negative distance from the main site geofence means that the equipment is inside the geofence. The positive distance from the subsite geofence means that the equipment is outside the subsite geofence. Since it's the first time this device was located inside the main site geofence, the `isEventPublished` parameter is set to `true`. The Operations Manager receives an email notification that equipment entered the geofence.
 
 ### Location 2 (47.63800,-122.132531)
 
@@ -299,7 +401,7 @@ In the preceding GeoJSON response, the negative distance from the main site geof
 
 4. Select the **GET** HTTP method.
 
-5. Enter the following URL. The request should look like the following URL (replace `{udid}` with the `udid` you saved in the [Upload Geofencing GeoJSON data section]).
+5. Enter the following URL. The request should look like the following URL (replace `{udid}` with the `udid` you saved in the [Upload Geofencing GeoJSON data] section).
 
    ```HTTP
    https://{geography}.atlas.microsoft.com/spatial/geofence/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2022-08-01&deviceId=device_01&udId={udId}&lat=47.63800&lon=-122.132531&searchBuffer=5&isAsync=True&mode=EnterAndExit
@@ -335,7 +437,7 @@ In the preceding GeoJSON response, the negative distance from the main site geof
     }
     ````
 
-In the preceding GeoJSON response, the equipment has remained in the main site geofence and hasn't entered the subsite geofence. As a result, the `isEventPublished` parameter is set to `false`, and the Operations Manager doesn't receive any email notifications.
+In the preceding GeoJSON response, the equipment remained in the main site geofence and didn't enter the subsite geofence. As a result, the `isEventPublished` parameter is set to `false`, and the Operations Manager doesn't receive any email notifications.
 
 ### Location 3 (47.63810783315048,-122.13336020708084)
 
@@ -347,7 +449,7 @@ In the preceding GeoJSON response, the equipment has remained in the main site g
 
 4. Select the **GET** HTTP method.
 
-5. Enter the following URL. The request should look like the following URL (replace `{udid}` with the `udid` you saved in the [Upload Geofencing GeoJSON data section]).
+5. Enter the following URL. The request should look like the following URL (replace `{udid}` with the `udid` you saved in the [Upload Geofencing GeoJSON data] section).
 
     ```HTTP
       https://{geography}.atlas.microsoft.com/spatial/geofence/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2022-08-01&deviceId=device_01&udid={udid}&lat=47.63810783315048&lon=-122.13336020708084&searchBuffer=5&isAsync=True&mode=EnterAndExit
@@ -383,7 +485,7 @@ In the preceding GeoJSON response, the equipment has remained in the main site g
     }
     ````
 
-In the preceding GeoJSON response, the equipment has remained in the main site geofence, but has entered the subsite geofence. As a result, the `isEventPublished` parameter is set to `true`. The Operations Manager receives an email notification indicating that the equipment has entered a geofence.
+In the preceding GeoJSON response, the equipment remained in the main site geofence, and entered the subsite geofence. As a result, the `isEventPublished` parameter is set to `true`. The Operations Manager receives an email notification indicating that the equipment entered a geofence.
 
 >[!NOTE]
 >If the equipment had moved into the subsite after business hours, no event would be published and the operations manager wouldn't receive any notifications.  
@@ -398,7 +500,7 @@ In the preceding GeoJSON response, the equipment has remained in the main site g
 
 4. Select the **GET** HTTP method.
 
-5. Enter the following URL. The request should look like the following URL (replace `{udid}` with the `udid` you saved in the [Upload Geofencing GeoJSON data section]).
+5. Enter the following URL. The request should look like the following URL (replace `{udid}` with the `udid` you saved in the [Upload Geofencing GeoJSON data] section).
 
     ```HTTP
     https://{geography}.atlas.microsoft.com/spatial/geofence/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2022-08-01&deviceId=device_01&udid={udid}&lat=47.637988&userTime=2023-01-16&lon=-122.1338344&searchBuffer=5&isAsync=True&mode=EnterAndExit
@@ -428,7 +530,7 @@ In the preceding GeoJSON response, the equipment has remained in the main site g
     }
     ````
 
-In the preceding GeoJSON response, the equipment has remained in the main site geofence, but has exited the subsite geofence. Notice, however, that the `userTime` value is after the `expiredTime` as defined in the geofence data. As a result, the `isEventPublished` parameter is set to `false`, and the Operations Manager doesn't receive an email notification.
+In the preceding GeoJSON response, the equipment remained in the main site geofence, but exited the subsite geofence. Notice, however, that the `userTime` value is after the `expiredTime` as defined in the geofence data. As a result, the `isEventPublished` parameter is set to `false`, and the Operations Manager doesn't receive an email notification.
 
 ### Location 5 (47.63799, -122.134505)
 
@@ -440,7 +542,7 @@ In the preceding GeoJSON response, the equipment has remained in the main site g
 
 4. Select the **GET** HTTP method.
 
-5. Enter the following URL. The request should look like the following URL (replace `{udid}` with the `udid` you saved in the [Upload Geofencing GeoJSON data section]).
+5. Enter the following URL. The request should look like the following URL (replace `{udid}` with the `udid` you saved in the [Upload Geofencing GeoJSON data] section).
 
     ```HTTP
     https://{geography}.atlas.microsoft.com/spatial/geofence/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2022-08-01&deviceId=device_01&udid={udid}&lat=47.63799&lon=-122.134505&searchBuffer=5&isAsync=True&mode=EnterAndExit
@@ -476,9 +578,9 @@ In the preceding GeoJSON response, the equipment has remained in the main site g
     }
     ````
 
-In the preceding GeoJSON response, the equipment has exited the main site geofence. As a result, the `isEventPublished` parameter is set to `true`, and the Operations Manager receives an email notification indicating that the equipment has exited a geofence.
+In the preceding GeoJSON response, the equipment exited the main site geofence. As a result, the `isEventPublished` parameter is set to `true`, and the Operations Manager receives an email notification indicating that the equipment exited a geofence.
 
-You can also [Send email notifications using Event Grid and Logic Apps]. For more information,see [Event handlers in Azure Event Grid].
+You can also [Send email notifications using Event Grid and Logic Apps]. For more information, see [Event handlers in Azure Event Grid].
 
 ## Clean up resources
 
@@ -495,18 +597,17 @@ There are no resources that require cleanup.
 [Azure portal]: https://portal.azure.com
 [Azure storage account]: /azure/storage/common/storage-account-create?tabs=azure-portal
 [Billing and pricing models]: /azure/logic-apps/logic-apps-pricing#standard-pricing
-[data registry]: /rest/api/maps/data-registry
+[Check the GeoJSON data upload status]: #check-the-geojson-data-upload-status
+[Data Upload API]: /rest/api/maps/data/upload
 [Geofencing GeoJSON data]: geofence-geojson.md
 [Handle content types in Azure Logic Apps]: ../logic-apps/logic-apps-content-type.md
-[How to create data registry]: how-to-create-data-registries.md
 [logic app]: ../event-grid/handler-webhooks.md#logic-apps
 [logic apps]: ../event-grid/handler-webhooks.md#logic-apps
 [Postman]: https://www.postman.com
-[Search Geofence Get API]: /rest/api/maps/spatial/getgeofence
 [Send email notifications using Event Grid and Logic Apps]: ../event-grid/publish-iot-hub-events-to-logic-apps.md
-[Spatial Geofence Get API]: /rest/api/maps/spatial/getgeofence
+[Spatial Geofence Get API]: /rest/api/maps/spatial/get-geofence
 [subscription key]: quick-demo-map-app.md#get-the-subscription-key-for-your-account
 [Event handlers in Azure Event Grid]: ../event-grid/event-handlers.md
 [three event types]: ../event-grid/event-schema-azure-maps.md
 [Tutorial: Send email notifications about Azure IoT Hub events using Event Grid and Logic Apps]: ../event-grid/publish-iot-hub-events-to-logic-apps.md
-[Upload Geofencing GeoJSON data section]: #upload-geofencing-geojson-data
+[Upload Geofencing GeoJSON data]: #upload-geofencing-geojson-data