Merge pull request #224698 from dominicbetts/adt-postman

Digital Twins: update Postman import instructions

Author: 19BMG00

articles/digital-twins/how-to-use-postman-with-digital-twins.md

@@ -1,13 +1,13 @@
 ---
 title: Call the Azure Digital Twins APIs with Postman
 titleSuffix: Azure Digital Twins
-description: Learn how to authorize, configure, and use Postman to call the Azure Digital Twins APIs.
+description: Learn how to authorize, configure, and use Postman to call the Azure Digital Twins APIs. This article shows you how to use both the control and data plane APIs.
 ms.author: baanders
 author: baanders
 ms.service: digital-twins
 services: digital-twins
 ms.topic: how-to
-ms.date: 09/06/2022
+ms.date: 01/23/2023
 ms.custom: contperf-fy21q4
 ---
 
@@ -41,7 +41,7 @@ Next, [download the desktop version of the Postman client](https://www.getpostma
 
 Now that you've set up Postman and your Azure Digital Twins instance, you'll need to get a bearer token that Postman requests can use to authorize against the Azure Digital Twins APIs.
 
-There are several possible ways to obtain this token. This article uses the [Azure CLI](/cli/azure/install-azure-cli) to sign into your Azure account and obtain a token that way.
+There are several possible ways to obtain this token. This article uses the [Azure CLI](/cli/azure/install-azure-cli) to sign into your Azure account and obtain a token.
 
 If you have an [Azure CLI installed locally](/cli/azure/install-azure-cli), you can start a command prompt on your machine to run the following commands.
 Otherwise, you can open an [Azure Cloud Shell](https://shell.azure.com) window in your browser and run the commands there.
@@ -54,7 +54,7 @@ Otherwise, you can open an [Azure Cloud Shell](https://shell.azure.com) window i
 
 2. Next, use the [az account get-access-token](/cli/azure/account#az-account-get-access-token) command to get a bearer token with access to the Azure Digital Twins service. In this command, you'll pass in the resource ID for the Azure Digital Twins service endpoint, in order to get an access token that can access Azure Digital Twins resources. 
 
-    The required context for the token depends on which set of APIs you're using, so use the tabs below to select between [data plane](concepts-apis-sdks.md#data-plane-apis) and [control plane](concepts-apis-sdks.md#control-plane-apis) APIs.
+    The required context for the token depends on which set of APIs you're using, so use the following tabs to select between [data plane](concepts-apis-sdks.md#data-plane-apis) and [control plane](concepts-apis-sdks.md#control-plane-apis) APIs.
 
     # [Data plane](#tab/data-plane)
     
@@ -78,7 +78,7 @@ Otherwise, you can open an [Azure Cloud Shell](https://shell.azure.com) window i
 
 3. Copy the value of `accessToken` in the result, and save it to use in the next section. This value is your **token value** that you'll provide to Postman to authorize your requests.
 
-   :::image type="content" source="media/how-to-use-postman-with-digital-twins/console-access-token.png" alt-text="Screenshot of the console showing the result of the az account get-access-token command. The accessToken field and its sample value is highlighted." lightbox="media/how-to-use-postman-with-digital-twins/console-access-token.png":::
+   :::image type="content" source="media/how-to-use-postman-with-digital-twins/console-access-token.png" alt-text="Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted." lightbox="media/how-to-use-postman-with-digital-twins/console-access-token.png":::
 
 >[!TIP]
 >This token is valid for at least five minutes and a maximum of 60 minutes. If you run out of time allotted for the current token, you can repeat the steps in this section to get a new one.
@@ -87,54 +87,22 @@ Next, you'll set up Postman to use this token to make API requests to Azure Digi
 
 ## About Postman collections
 
-Requests in Postman are saved in *collections* (groups of requests). When you create a collection to group your requests, you can apply common settings to many requests at once. This can greatly simplify authorization if you plan to create more than one request against the Azure Digital Twins APIs, as you only have to configure these details once for the entire collection.
+Requests in Postman are saved in *collections* (groups of requests). When you create a collection to group your requests, you can apply common settings to many requests at once. Common settings can greatly simplify authorization if you plan to create more than one request against the Azure Digital Twins APIs, as you only have to configure these details once for the entire collection.
 
-When working with Azure Digital Twins, you can get started by importing a [pre-built collection of all the Azure Digital Twins requests](#import-collection-of-azure-digital-twins-apis). You may want to do this if you're exploring the APIs and want to quickly set up a project with request examples.
+When working with Azure Digital Twins, you can get started by importing a [pre-built collection of all the Azure Digital Twins requests](#import-collection-of-azure-digital-twins-apis). You may want to import this collection if you're exploring the APIs and want to set up a project quickly with request examples.
 
 Alternatively, you can also choose to start from scratch, by [creating your own empty collection](#create-your-own-collection) and populating it with individual requests that call only the APIs you need. 
 
 The following sections describe both of these processes. The rest of the article takes place in your local Postman application, so go ahead and open the Postman application on your computer now.
 
 ## Import collection of Azure Digital Twins APIs
 
-A quick way to get started with Azure Digital Twins in Postman is to import a pre-built collection of requests for the Azure Digital Twins APIs.
-
-### Download the collection file
-
-The first step in importing the API set is to download a collection. Choose the tab below for your choice of data plane or control plane to see the pre-built collection options.
-
-# [Data plane](#tab/data-plane)
-
-There are currently two Azure Digital Twins data plane collections available for you to choose from:
-* [Azure Digital Twins Postman Collection](https://github.com/microsoft/azure-digital-twins-postman-samples): This collection provides a simple getting started experience for Azure Digital Twins in Postman. The requests include sample data, so you can run them with minimal edits required. Choose this collection if you want a digestible set of key API requests containing sample information.
-    - To find the collection, navigate to the repo link and open the file named *postman_collection.json*.
-* [Azure Digital Twins data plane Swagger](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/digitaltwins/data-plane/Microsoft.DigitalTwins): This repo contains complete Swagger files for the Azure Digital Twins API set, which can be downloaded and imported to Postman as a collection. These files provide a comprehensive set of every API request, but with empty data bodies rather than sample data. Choose this collection if you want to have access to every API call and fill in all the data yourself. You should also use this collection if you need a specific version of the APIs (like one that supports a preview feature).
-    - To find the collection, navigate to the repo link and choose the folder for your preferred spec version. From here, open the file called *digitaltwins.json*.
-
-# [Control plane](#tab/control-plane)
-
-The collection currently available for control plane is the [Azure Digital Twins control plane Swagger](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/digitaltwins/data-plane/Microsoft.DigitalTwins). This repo contains the complete Swagger file for the Azure Digital Twins API set, which can be downloaded and imported to Postman as a collection. These files provide a comprehensive set of every API request.
-
-To find the collection, navigate to the repo link and choose the folder for your preferred spec version. From here, open the file called *digitaltwins.json*.
-
----
-
-Here's how to download your chosen collection to your machine so that you can import it into Postman.
-1. Use the links above to open the collection file in GitHub in your browser.
-1. Select the **Raw** button to open the raw text of the file.
-   :::image type="content" source="media/how-to-use-postman-with-digital-twins/swagger-raw.png" alt-text="Screenshot of the data plane digitaltwins.json file in GitHub. There's a highlight around the Raw button." lightbox="media/how-to-use-postman-with-digital-twins/swagger-raw.png":::
-1. Copy the text from the window, and paste it into a new file on your machine.
-1. Save the file with a .json extension (the file name can be whatever you want, as long as you can remember it to find the file later).
-
-### Import the collection
-
-Next, import the collection into Postman.
+A quick way to get started with Azure Digital Twins in Postman is to import a pre-built collection of requests for the control plane and data plane Azure Digital Twins APIs.
 
 1. From the main Postman window, select the **Import** button.
     :::image type="content" source="media/how-to-use-postman-with-digital-twins/postman-import-collection.png" alt-text="Screenshot of a newly opened Postman window. The 'Import' button is highlighted." lightbox="media/how-to-use-postman-with-digital-twins/postman-import-collection.png":::
 
-1. In the **Import** window that follows, select **Upload Files** and navigate to the collection file on your machine that you created earlier. Select Open.
-1. Select the **Import** button to confirm.
+1. In the **Import** window that follows, select **Link** and enter the following URL: `https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json`. Then select **Import** to confirm.
 
    :::image type="content" source="media/how-to-use-postman-with-digital-twins/postman-import-collection-2.png" alt-text="Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button." lightbox="media/how-to-use-postman-with-digital-twins/postman-import-collection-2.png":::
 
@@ -160,27 +128,30 @@ Follow these steps to add a bearer token to the collection for authorization. Us
 
     :::image type="content" source="media/how-to-use-postman-with-digital-twins/postman-paste-token-imported.png" alt-text="Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted." lightbox="media/how-to-use-postman-with-digital-twins/postman-paste-token-imported.png":::
 
-### Additional configuration
+    > [!TIP]
+    > You must use the correct token for the type of API you're using. There is one access token for data plane APIS and another for control plane APIs.
 
-# [Data plane](#tab/data-plane)
+### Other configuration
 
-If you're making a [data plane](concepts-apis-sdks.md#data-plane-apis) collection, help the collection connect easily to your Azure Digital Twins resources by setting some variables provided with the collections. When many requests in a collection require the same value (like the host name of your Azure Digital Twins instance), you can store the value in a variable that applies to every request in the collection. Both of the downloadable collections for Azure Digital Twins come with pre-created variables that you can set at the collection level.
+You can help the collection connect easily to your Azure Digital Twins resources by setting some variables provided with the collection. When many requests in a collection require the same value (like the host name of your Azure Digital Twins instance), you can store the value in a variable that applies to every request in the collection. The Azure Digital Twins collection comes with pre-created variables that you can set at the collection level.
 
 1. Still in the edit dialog for your collection, move to the **Variables** tab.
 
-1. Use your instance's **host name** from the [Prerequisites section](#prerequisites) to set the CURRENT VALUE field of the relevant variable. Select **Save**.
+1. Use the following table to set the values of the variables in the collection:
+
+    | Variable | API set | Description |
+    | -------- | ------- | ----------- |
+    | `digitaltwins-hostname` | Data plane | The host name of your Azure Digital Twins instance. You can find this value on the overview page for your instance in the Portal. |
+    | `subscriptionId` | Control plane | Your Azure subscription ID. |
+    | `digitalTwinInstance` | Control plane | The name of your Azure Digital Twins instance. |
 
     :::image type="content" source="media/how-to-use-postman-with-digital-twins/postman-variables-imported.png" alt-text="Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted." lightbox="media/how-to-use-postman-with-digital-twins/postman-variables-imported.png":::
 
 1. If your collection has extra variables, fill and save those values as well.
 
-When you're finished with the above steps, you're done configuring the collection. You can close the editing tab for the collection if you want.
-
-# [Control plane](#tab/control-plane)
+1.  Select **Save**.
 
-If you're making a [control plane](concepts-apis-sdks.md#control-plane-apis) collection, you've done everything that you need to configure the collection. You can close the editing tab for the collection if you want, and proceed to the next section.
-
---- 
+When you're finished with the above steps, you're done configuring the collection. You can close the editing tab for the collection if you want.
 
 ### Explore requests
 
@@ -192,19 +163,21 @@ You can edit the details of a request in the Postman collection using these step
 
 1. Select it from the list to pull up its editable details. 
 
-1. Fill in values for the variables listed in the **Params** tab under **Path Variables**.
+1. Most of the requests in the sample collection are pre-configured to run without making any further changes.
 
-    :::image type="content" source="media/how-to-use-postman-with-digital-twins/postman-request-details-imported.png" alt-text="Screenshot of Postman. The collection is expanded to show a request. The 'Path Variables' section is highlighted in the request details." lightbox="media/how-to-use-postman-with-digital-twins/postman-request-details-imported.png":::
+1. The following screenshot shows the **DigitalTwinModels Add** API. On the **Body** tab you can see the JSON payload that defines the new model to add:
+
+1. Fill in values for the variables listed in the **Params** tab under **Path Variables**.
 
-1. Provide any necessary **Headers** or **Body** details in the respective tabs.
+    :::image type="content" source="media/how-to-use-postman-with-digital-twins/postman-request-details-imported.png" alt-text="Screenshot of Postman. The collection is expanded to show the body tab of a request." lightbox="media/how-to-use-postman-with-digital-twins/postman-request-details-imported.png":::
 
-Once all the required details are provided, you can run the request with the **Send** button.
+1. To run the request, use the **Send** button.
 
-You can also add your own requests to the collection, using the process described in the [Add an individual request](#add-an-individual-request) section below.
+You can also add your own requests to the collection, using the process described in the [Add an individual request](#add-an-individual-request) section.
 
 ## Create your own collection
 
-Instead of importing the existing collection of all Azure Digital Twins APIs, you can also create your own collection from scratch. You can then populate it with individual requests using the [Azure Digital Twins REST API reference documentation](/rest/api/azure-digitaltwins/).
+Instead of importing the existing collection of Azure Digital Twins APIs, you can also create your own collection from scratch. You can then populate it with individual requests using the [Azure Digital Twins REST API reference documentation](/rest/api/azure-digitaltwins/).
 
 ### Create a Postman collection