Skip to content

Commit 8f00f61

Browse files
v-ccolinv-ccolin
authored
Merge pull request #303580 from aksjosh007/security/remove_well_delivery
Remove Postman occurrence well delivery ddms swagger
2 parents f9f577d + 36acd09 commit 8f00f61

File tree

1 file changed

+174
-116
lines changed

1 file changed

+174
-116
lines changed

‎articles/energy-data-services/tutorial-well-delivery-ddms.md

Lines changed: 174 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -13,160 +13,218 @@ ms.custom: template-tutorial
1313

1414
# Tutorial: Work with well data records by using Well Delivery DDMS APIs
1515

16-
Use Well Delivery Domain Data Management Services (DDMS) APIs in Postman to work with well data in your instance of Azure Data Manager for Energy.
16+
This tutorial demonstrates how to utilize Well Delivery Domain Data Management Services (DDMS) APIs with cURL to manage well record within an Azure Data Manager for Energy instance.
1717

1818
In this tutorial, you learn how to:
1919

2020
> [!div class="checklist"]
2121
>
22-
> - Set up Postman to use a Well Delivery DDMS collection.
23-
> - Set up Postman to use a Well Delivery DDMS environment.
24-
> - Send requests via Postman.
25-
> - Generate an authorization token.
2622
> - Use Well Delivery DDMS APIs to work with well data records.
2723
2824
For more information about DDMS, see [DDMS concepts](concepts-ddms.md).
2925

3026
## Prerequisites
31-
32-
- An Azure subscription
33-
- An instance of [Azure Data Manager for Energy](quickstart-create-microsoft-energy-data-services-instance.md) created in your Azure subscription
27+
* An Azure subscription
28+
* An instance of [Azure Data Manager for Energy](quickstart-create-microsoft-energy-data-services-instance.md) created in your Azure subscription
29+
* cURL command-line tool installed on your machine
30+
* Generate the service principal access token to call the Well Delivery APIs. See [How to generate auth token](how-to-generate-auth-token.md).
3431

3532
## Get your Azure Data Manager for Energy instance details
3633

37-
The first step is to get the following information from your [Azure Data Manager for Energy instance](quickstart-create-microsoft-energy-data-services-instance.md) in the [Azure portal](https://portal.azure.com/?microsoft_azure_marketplace_ItemHideKey=Microsoft_Azure_OpenEnergyPlatformHidden):
38-
39-
| Parameter | Value | Example |
40-
| ------------------ | ------------------------ |-------------------------------------- |
41-
| `CLIENT_ID` | Application (client) ID | `00001111-aaaa-2222-bbbb-3333cccc4444` |
42-
| `CLIENT_SECRET` | Client secrets | `_fl******************` |
43-
| `TENANT_ID` | Directory (tenant) ID | `72f988bf-86f1-41af-91ab-xxxxxxxxxxxx` |
44-
| `SCOPE` | Application (client) ID | `00001111-aaaa-2222-bbbb-3333cccc4444` |
45-
| `base_uri` | URI | `<instance>.energy.azure.com` |
46-
| `data-partition-id` | Data partitions | `<data-partition-id>` |
47-
48-
You'll use this information later in the tutorial.
49-
50-
## Set up Postman
51-
52-
1. Download and install the [Postman](https://www.postman.com/downloads/) desktop app.
53-
54-
1. Import the following files in Postman:
55-
56-
- [Well Delivery DDMS Postman collection](https://raw.githubusercontent.com/microsoft/meds-samples/main/postman/WelldeliveryDDMS.postman_collection.json)
57-
- [Well Delivery DDMS Postman environment](https://raw.githubusercontent.com/microsoft/meds-samples/main/postman/WelldeliveryDDMSEnviroment.postman_environment.json)
58-
59-
To import the files:
60-
61-
1. Create two JSON files on your computer by copying the data that's in the collection and environment files.
62-
63-
1. In Postman, select **Import** > **Files** > **Choose Files**, and then select the two JSON files on your computer.
64-
65-
1. In **Import Entities** in Postman, select **Import**.
66-
67-
:::image type="content" source="media/tutorial-well-delivery/import-files.png" alt-text="Screenshot that shows importing collection and environment files." lightbox="media/tutorial-well-delivery/import-files.png":::
68-
69-
1. In the Postman environment, update **CURRENT VALUE** with the information from your Azure Data Manager for Energy instance:
70-
71-
1. In Postman, on the left menu, select **Environments**, and then select **WellDelivery Environment**.
72-
73-
1. In the **CURRENT VALUE** column, enter the information from the table in the [Get your Azure Data Manager for Energy instance details](#get-your-azure-data-manager-for-energy-instance-details) section of this tutorial.
74-
75-
:::image type="content" source="media/tutorial-well-delivery/postman-environment-current-values.png" alt-text="Screenshot that shows where to enter current values in the Well Delivery DDMS environment.":::
76-
77-
## Send a Postman request
78-
79-
The Postman collection for Well Delivery DDMS contains requests that you can use to interact with data about wells, wellbores, well logs, and well trajectory in your Azure Data Manager for Energy instance.
80-
81-
82-
## Generate a token for APIs
83-
84-
Generate a token that you can use to work with Well Delivery DDMS APIs:
85-
86-
1. Import the following cURL command in Postman to generate a bearer token. Use the values from your Azure Data Manager for Energy instance.
87-
88-
```bash
89-
curl --location --request POST 'https://login.microsoftonline.com/{{TENANT_ID}}/oauth2/v2.0/token' \
90-
--header 'Content-Type: application/x-www-form-urlencoded' \
91-
--data-urlencode 'grant_type=client_credentials' \
92-
--data-urlencode 'client_id={{CLIENT_ID}}' \
93-
--data-urlencode 'client_secret={{CLIENT_SECRET}}' \
94-
--data-urlencode 'scope={{SCOPE}}'
95-
```
34+
To proceed, gather the following details from your [Azure Data Manager for Energy instance](quickstart-create-microsoft-energy-data-services-instance.md) via the [Azure portal](https://portal.azure.com/?microsoft_azure_marketplace_ItemHideKey=Microsoft_Azure_OpenEnergyPlatformHidden):
9635

97-
:::image type="content" source="media/tutorial-well-delivery/postman-generate-token.png" alt-text="Screenshot of cURL code in a Well Delivery DDMS token." lightbox="media/tutorial-well-delivery/postman-generate-token.png":::
36+
| Parameter | Description | Example | Where to find this value |
37+
| ------------------ | -------------------------- |-------------------------------------- |-------------------------------------- |
38+
| `client_id` | Application (client) ID | `00001111-aaaa-2222-bbbb-3333cccc4444`| You use this app or client ID when registering the application with the Microsoft identity platform. See [Register an application](../active-directory/develop/quickstart-register-app.md#register-an-application)|
39+
| `client_secret` | Client secret | `_fl******************` |Sometimes called an *application password*, a client secret is a string value that your app can use in place of a certificate to identity itself. See [Add a client secret](../active-directory/develop/quickstart-register-app.md#add-a-client-secret).|
40+
| `tenant_id` | Directory (tenant) ID | `72f988bf-86f1-41af-91ab-xxxxxxxxxxxx`| Hover over your account name in the Azure portal to get the directory or tenant ID. Alternatively, search for and select **Microsoft Entra ID** > **Properties** > **Tenant ID** in the Azure portal. |
41+
| `base_url` | Instance URL | `https://<instance>.energy.azure.com` | Find this value on the overview page of the Azure Data Manager for Energy instance.|
42+
| `data_partition_id`| Data partition name | `opendes` | Find this value on the overview page of the Azure Data Manager for Energy instance.|
43+
| `access_token` | Access token value | `0.ATcA01-XWHdJ0ES-qDevC6r...........`| Follow [How to generate auth token](how-to-generate-auth-token.md) to create an access token and save it.|
9844

99-
1. Use the token output to update `access_token` in your Well Delivery DDMS environment. Then, you can use the bearer token as an authorization type in other API calls.
10045

10146
## Use Well Delivery DDMS APIs to work with well data records
10247

103-
Successfully completing the Postman requests that are described in the following Well Delivery DDMS APIs indicates successful ingestion and retrieval of well records in your Azure Data Manager for Energy instance.
48+
### Create a legal tag
49+
50+
Create a legal tag for data compliance.
51+
52+
Run the following `cURL` command to create a legal tag:
53+
54+
```bash
55+
curl -X POST "https://{base_url}/api/legal/v1/legaltags" \
56+
-H "Authorization: Bearer <access_token>" \
57+
-H "Content-Type: application/json" \
58+
-H "data-partition-id: <data_partition_id>" \
59+
-d '{
60+
"name": "LegalTagName",
61+
"description": "Legal Tag added for Well",
62+
"properties": {
63+
"contractId": "123456",
64+
"countryOfOrigin": ["US", "CA"],
65+
"dataType": "Third Party Data",
66+
"exportClassification": "EAR99",
67+
"originator": "xyz",
68+
"personalData": "No Personal Data",
69+
"securityClassification": "Private",
70+
"expirationDate": "2025-12-25"
71+
}
72+
}'
73+
```
74+
75+
**Sample Response:**
76+
```json
77+
{
78+
"name": "LegalTagName",
79+
"status": "Created"
80+
}
81+
```
82+
83+
For more information, see [Manage legal tags](how-to-manage-legal-tags.md).
84+
85+
### Add users to an entitlement group
86+
87+
For users to have the proper permissions to make Well Delivery DDMS API calls, they must be part of the `data.default.viewers@{data-partition-id}.dataservices.energy` and `data.default.owners@<data_partition_id>.dataservices.energy` entitlement groups. This call adds a user to the proper group.
88+
89+
Follow the [Manage users](how-to-manage-users.md) guide to add appropriate entitlements for the user .
10490

10591
### Create a well record
10692

10793
Create a well record in your Azure Data Manager for Energy instance.
10894

109-
API: **UC1** > **entity_create well**
110-
111-
Method: `PUT`
112-
113-
:::image type="content" source="media/tutorial-well-delivery/postman-api-create-well.png" alt-text="Screenshot that shows the API that creates a well record." lightbox="media/tutorial-well-delivery/postman-api-create-well.png":::
95+
```bash
96+
curl --request PUT \
97+
--url https://{base_url}/api/well-delivery/storage/v1/well \
98+
--header 'Authorization: Bearer <access_token>' \
99+
--header 'Content-Type: application/json' \
100+
--header 'data-partition-id: <data_partition_id>' \
101+
--data '{
102+
"id":"<data_partition_id>:master-data--Well:well-1753861267 434",
103+
"kind": "osdu:wks:master-data--Well:1.0.0",
104+
"acl": {
105+
"viewers": [
106+
"data.default.viewers@<data_partition_id>.dataservices.energy"
107+
],
108+
"owners": [
109+
"data.default.owners@<data_partition_id>.dataservices.energy"
110+
]
111+
},
112+
"legal": {
113+
"legaltags": [
114+
"LegalTagName"
115+
],
116+
"otherRelevantDataCountries": [
117+
"US"
118+
]
119+
},
120+
"data": {
121+
"ExistenceKind": "namespace:reference-data--ExistenceKind:planned:",
122+
"FacilityName": "Well-Test"
123+
}
124+
}'
125+
```
126+
127+
**Sample Response:**
128+
```json
129+
{
130+
"created entity": "well-1753861267434:1753861269454"
131+
}
132+
```
114133

115134
### Create a wellbore record
116135

117136
Create a wellbore record in your Azure Data Manager for Energy instance.
118137

119-
API: **UC1** > **entity_create wellbore**
120-
121-
Method: `PUT`
122-
123-
:::image type="content" source="media/tutorial-well-delivery/postman-api-create-well-bore.png" alt-text="Screenshot that shows the API that creates a wellbore record." lightbox="media/tutorial-well-delivery/postman-api-create-well-bore.png":::
124-
125-
### Get a well version
126-
127-
Get a well record based on a specific well ID.
138+
```bash
139+
curl --request PUT \
140+
--url https://{base_url}/api/well-delivery/storage/v1/ wellbore \
141+
--header 'Authorization: Bearer <access_token>' \
142+
--header 'Content-Type: application/json' \
143+
--header 'data-partition-id: <data_partition_id>' \
144+
--data '{
145+
"id": "dp1:master-data--Wellbore:wellbore-1753861298505",
146+
"kind": "osdu:wks:master-data--Wellbore:1.0.0",
147+
"acl": {
148+
"viewers": [
149+
"data.default.viewers@<data_partition_id>.dataservices.energy"
150+
],
151+
"owners": [
152+
"data.default.owners@<data_partition_id>.dataservices.energy"
153+
]
154+
},
155+
"legal": {
156+
"legaltags": [
157+
"LegalTagName"
158+
],
159+
"otherRelevantDataCountries": [
160+
"US"
161+
]
162+
},
163+
"data": {
164+
"ExistenceKind": "namespace:reference-data--ExistenceKind:planned:",
165+
"WellID": "<data_partition_id>:master-data--Well:well-1753861298505:1753861300000",
166+
"Name": "Demo wellbore name"
167+
}
168+
}'
169+
```
170+
171+
**Sample Response:**
172+
```json
173+
{
174+
"created entity": "wellbore-1753861298505:1753861301020"
175+
}
176+
```
128177

129-
API: **UC1** > **entity_create well Copy**
130-
131-
Method: `GET`
132-
133-
:::image type="content" source="media/tutorial-well-delivery/postman-api-get-well.png" alt-text="Screenshot that shows the API that gets a well record based on a specific well ID." lightbox="media/tutorial-well-delivery/postman-api-get-well.png":::
134178

135179
### Create an activity plan
136180

137181
Create an activity plan.
138182

139-
API: **UC1** > **entity_create activityplan**
140-
141-
Method: `PUT`
142-
143-
:::image type="content" source="media/tutorial-well-delivery/postman-api-create-activity-plan.png" alt-text="Screenshot that shows the API that creates an activity plan." lightbox="media/tutorial-well-delivery/postman-api-create-activity-plan.png":::
144-
145-
### Get an activity plan by well ID
146-
147-
Get the activity plan object for a specific well ID.
148-
149-
API: **UC2** > **activity_plans_by_well**
150-
151-
Method: `GET`
152-
153-
:::image type="content" source="media/tutorial-well-delivery/postman-api-activity-plans-by-well.png" alt-text="Screenshot of the API that gets an activity plan by well ID." lightbox="media/tutorial-well-delivery/postman-api-activity-plans-by-well.png":::
154-
155-
### Delete a wellbore record
156-
157-
You can delete a wellbore record in your Azure Data Manager for Energy instance by using Well Delivery DDMS APIs. The following screenshot shows an example.
158-
159-
:::image type="content" source="media/tutorial-well-delivery/postman-api-delete-well-bore.png" alt-text="Screenshot that shows how to use an API to delete a wellbore record.":::
160-
161-
### Delete a well record
162-
163-
You can delete a well record in your Azure Data Manager for Energy instance by using Well Delivery DDMS APIs. The following screenshot shows an example.
164-
165-
:::image type="content" source="media/tutorial-well-delivery/postman-api-delete-well.png" alt-text="Screenshot that shows how to use an API to delete a well record.":::
183+
```bash
184+
185+
curl --request PUT \
186+
--url https://{base_url}/api/well-delivery/storage/v1/activityplan \
187+
--header 'Authorization: Bearer <access_token>' \
188+
--header 'Content-Type: application/json' \
189+
--header 'data-partition-id: <data_partition_id>' \
190+
--data '{
191+
"id": "dp1:master-data--ActivityPlan:activityplan-1753861290577",
192+
"kind": "osdu:wks:master-data--ActivityPlan:1.0.0",
193+
"acl": {
194+
"viewers": [
195+
"data.default.viewers@<data_partition_id>.dataservices.energy"
196+
],
197+
"owners": [
198+
"data.default.owners@<data_partition_id>.dataservices.energy"
199+
]
200+
},
201+
"legal": {
202+
"legaltags": [
203+
"LegalTagName"
204+
],
205+
"otherRelevantDataCountries": [
206+
"US"
207+
]
208+
},
209+
"data": {
210+
"ExistenceKind": "namespace:reference-data--ExistenceKind:planned:",
211+
"WellboreID": "<data_partition_id>:master-data--Wellbore:wellbore-1753861290577:1753861293139"
212+
}
213+
}'
214+
215+
```
216+
**Sample Response:**
217+
```json
218+
{
219+
"created entity" : "activityplan-1753861290577:1753861294109"
220+
}
221+
```
166222

167223
## Next steps
168224

169225
Go to the next tutorial to learn how to work with well data by using Wellbore DDMS APIs:
170226

171227
> [!div class="nextstepaction"]
172228
> [Tutorial: Work with well data records by using Wellbore DDMS APIs](tutorial-wellbore-ddms.md)
229+
230+
For more information on the Well Delivery DDMS REST APIs in Azure Data Manager for Energy, see the OpenAPI specifications available in the [adme-samples](https://microsoft.github.io/adme-samples/) GitHub repository.

0 commit comments

Comments
 (0)