Skip to content

Commit c86c3e8

Browse files
author
Preeti Singh
committed
changing wellbore
1 parent 8f81cae commit c86c3e8

File tree

1 file changed

+214
-91
lines changed

1 file changed

+214
-91
lines changed

‎articles/energy-data-services/tutorial-wellbore-ddms.md

Lines changed: 214 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -1,168 +1,291 @@
11
---
22
title: "Tutorial: Work with well data records by using Wellbore DDMS APIs"
33
titleSuffix: Microsoft Azure Data Manager for Energy
4-
description: Learn how to work with well data records in your Azure Data Manager for Energy instance by using Wellbore Domain Data Management Services (DDMS) APIs in Postman.
5-
author: vkamani21
6-
ms.author: vkamani
4+
description: Learn how to work with well data records in your Azure Data Manager for Energy instance by using Wellbore Domain Data Management Services (DDMS) APIs using cURL.
5+
author: Preetisingh
6+
ms.author: preetisingh
77
ms.service: azure-data-manager-energy
88
ms.topic: tutorial
9-
ms.date: 09/07/2022
9+
ms.date: 22/07/2025
1010
ms.custom: template-tutorial
1111

1212
#Customer intent: As a developer, I want to learn how to use the Wellbore DDMS APIs so that I can store and retrieve similar kinds of data records.
1313
---
1414

1515
# Tutorial: Work with well data records by using Wellbore DDMS APIs
1616

17-
Use Wellbore Domain Data Management Services (DDMS) APIs in Postman to work with well data in your instance of Azure Data Manager for Energy.
17+
Use Wellbore Domain Data Management Services (DDMS) APIs to work with well data in your instance of Azure Data Manager for Energy.
1818

1919
In this tutorial, you learn how to:
2020

2121
> [!div class="checklist"]
22-
>
23-
> - Set up Postman to use a Wellbore DDMS collection.
24-
> - Set up Postman to use a Wellbore DDMS environment.
25-
> - Send requests via Postman.
26-
> - Generate an authorization token.
2722
> - Use Wellbore DDMS APIs to work with well data records.
2823
2924
For more information about DDMS, see [DDMS concepts](concepts-ddms.md).
3025

3126
## Prerequisites
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 Seismic APIs. See [How to generate auth token](how-to-generate-auth-token.md).
3231

33-
- An Azure subscription
34-
- An instance of [Azure Data Manager for Energy](quickstart-create-microsoft-energy-data-services-instance.md) created in your Azure subscription
32+
### Get details for the Azure Data Manager for Energy instance
3533

36-
## Get your Azure Data Manager for Energy instance details
34+
* For this tutorial, you need the following parameters:
3735

38-
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):
36+
| Parameter | Value to use | Example | Where to find this value |
37+
|----|----|----|----|
38+
| `DNS` | URI | `<instance>.energy.azure.com` | Find this value on the overview page of the Azure Data Manager for Energy instance. |
39+
| `data-partition-id` | Data partitions | `<data-partition-id>` | Find this value on the Data Partitions section within the Azure Data Manager for Energy instance. |
40+
| `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.|
3941

40-
| Parameter | Value | Example |
41-
| ------------------ | ------------------------ |-------------------------------------- |
42-
| `client_id` | Application (client) ID | `00001111-aaaa-2222-bbbb-3333cccc4444` |
43-
| `client_secret` | Client secrets | `_fl******************` |
44-
| `tenant_id` | Directory (tenant) ID | `72f988bf-86f1-41af-91ab-xxxxxxxxxxxx` |
45-
| `base_url` | URL | `https://<instance>.energy.azure.com` |
46-
| `data-partition-id` | Data partitions | `<data-partition-name>` |
42+
Follow the [Manage users](how-to-manage-users.md) guide to add appropriate entitlements for the user who's running this tutorial.
4743

48-
You'll use this information later in the tutorial.
44+
### Set up your environment
4945

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-
- [Wellbore DDMS Postman collection](https://raw.githubusercontent.com/microsoft/meds-samples/main/postman/WellboreDDMS.postman_collection.json)
57-
- [Wellbore DDMS Postman environment](https://raw.githubusercontent.com/microsoft/meds-samples/main/postman/WellboreDDMSEnvironment.postman_environment.json)
58-
59-
To import the files:
60-
61-
1. Select **Import** in Postman.
62-
63-
:::image type="content" source="media/tutorial-ddms/postman-import-button.png" alt-text="Screenshot that shows the Import button in Postman." lightbox="media/tutorial-ddms/postman-import-button.png":::
64-
65-
1. Paste the URL of each file into the search box.
66-
67-
:::image type="content" source="media/tutorial-ddms/postman-import-search.png" alt-text="Screenshot that shows importing collection and environment files in Postman via URL." lightbox="media/tutorial-ddms/postman-import-search.png":::
68-
69-
1. In the Postman environment, update **Current value** with the information from your Azure Data Manager for Energy instance details:
70-
71-
1. In Postman, on the left menu, select **Environments**, and then select **Wellbore DDMS 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-wellbore-ddms/postman-environment-current-values.png" alt-text="Screenshot that shows where to enter current values in the Wellbore DDMS environment.":::
76-
77-
## Send an example Postman request
78-
79-
The Postman collection for Wellbore 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-
1. In Postman, on the left menu, select **Collections**, and then select **Wellbore DDMS**. Under **Setup**, select **Get an SPN Token**.
82-
83-
1. In the environment dropdown list in the upper-right corner, select **Wellbore DDMS Environment**.
84-
85-
:::image type="content" source="media/tutorial-wellbore-ddms/postman-get-spn-token.png" alt-text="Screenshot that shows selections for getting an SPN token and choosing an environment." lightbox="media/tutorial-wellbore-ddms/postman-get-spn-token.png":::
86-
87-
1. To send the request, select **Send**.
88-
89-
:::image type="content" source="media/tutorial-wellbore-ddms/postman-request-send.png" alt-text="Screenshot that shows the Send button for a request in Postman.":::
90-
91-
1. The request validates the actual API response code against the expected response code. Select the **Test Results** tab to see whether the request succeeded or failed.
92-
93-
Here's an example of a successful Postman call:
94-
95-
:::image type="content" source="media/tutorial-wellbore-ddms/postman-test-success.png" alt-text="Screenshot that shows success for a Postman call." lightbox="media/tutorial-wellbore-ddms/postman-test-success.png":::
96-
97-
Here's an example of a failed Postman call:
98-
99-
:::image type="content" source="media/tutorial-wellbore-ddms/postman-test-failure.png" alt-text="Screenshot that shows failure for a Postman call." lightbox="media/tutorial-wellbore-ddms/postman-test-failure.png":::
46+
Ensure you have `cURL` installed on your system. You will use it to make API calls.
10047

10148
## Use Wellbore DDMS APIs to work with well data records
10249

103-
Successfully completing the Postman requests that are described in the following Wellbore DDMS APIs indicates successful ingestion and retrieval of well records in your Azure Data Manager for Energy instance.
50+
Successfully completing the cURL requests that are described in the following Wellbore DDMS APIs indicates successful ingestion and retrieval of well records in your Azure Data Manager for Energy instance.
10451

10552
### Create a legal tag
10653

10754
Create a legal tag that's automatically added to your Wellbore DDMS environment for data compliance.
10855

109-
API: **Setup** > **Create Legal Tag for WDMS**
110-
111-
Method: `POST`
112-
113-
:::image type="content" source="media/tutorial-wellbore-ddms/postman-api-create-legal-tag.png" alt-text="Screenshot that shows the API that creates a legal tag." lightbox="media/tutorial-wellbore-ddms/postman-api-create-legal-tag.png":::
56+
Run the following `cURL` command to create a legal tag:
57+
58+
```bash
59+
curl -X POST "https://<DNS>/api/legal/v1/legaltags" \
60+
-H "Authorization: Bearer <access_token>" \
61+
-H "Content-Type: application/json" \
62+
-H "data-partition-id: <data-partition-id>" \
63+
-d '{
64+
"name": "LegalTagName",
65+
"description": "Legal Tag added for Well",
66+
"properties": {
67+
"contractId": "123456",
68+
"countryOfOrigin": ["US", "CA"],
69+
"dataType": "Third Party Data",
70+
"exportClassification": "EAR99",
71+
"originator": "xyz",
72+
"personalData": "No Personal Data",
73+
"securityClassification": "Private",
74+
"expirationDate": "2025-12-25"
75+
}
76+
}'
77+
```
78+
79+
**Sample Response:**
80+
```json
81+
{
82+
"name": "LegalTagName",
83+
"status": "Created"
84+
}
85+
```
11486

11587
For more information, see [Manage legal tags](how-to-manage-legal-tags.md).
11688

11789
### Create a well record
11890

11991
Create a well record in your Azure Data Manager for Energy instance.
12092

121-
API: **Well** > **Create Well**
122-
12393
Method: `POST`
12494

125-
:::image type="content" source="media/tutorial-wellbore-ddms/postman-api-create-well.png" alt-text="Screenshot that shows the API that creates a well record." lightbox="media/tutorial-wellbore-ddms/postman-api-create-well.png":::
95+
```bash
96+
curl -X GET "https://<DNS>/api/os-wellbore-ddms/ddms/v3/wells/<well_id>/versions" \
97+
-H "Authorization: Bearer <access_token>" \
98+
-H "data-partition-id: <data-partition-id>" \
99+
-H "Content-Type: application/json" \
100+
-d '[
101+
{
102+
"acl": {
103+
"owners": [
104+
"data.default.owners@{{entitlement_domain}}"
105+
],
106+
"viewers": [
107+
"data.default.viewers@{{entitlement_domain}}"
108+
]
109+
},
110+
"data": {
111+
"ExtensionProperties": {},
112+
"FacilityName": "{{wellbore_well_name}}",
113+
"FacilityNameAliases": [
114+
{
115+
"AliasName": "20-000-00000-00",
116+
"AliasNameTypeID": "{{DATA_PARTITION_ID}}:reference-data--AliasNameType:UniqueIdentifier:"
117+
}
118+
]
119+
},
120+
"id": "{{DATA_PARTITION_ID}}:master-data--Well:{{wellbore_well_id}}",
121+
"kind": "osdu:wks:master-data--Well:1.1.0",
122+
"legal": {
123+
"legaltags": [
124+
"{{legal_dafault_tag}}"
125+
],
126+
"otherRelevantDataCountries": [
127+
"FR",
128+
"US"
129+
],
130+
"status": "compliant"
131+
}
132+
}
133+
]'
134+
135+
```
136+
137+
**Sample Response:**
138+
```json
139+
{
140+
"recordCount": 1,
141+
"recordIdVersions": [
142+
"opendes:master-data--Well:122:1753292228903506"
143+
],
144+
"recordIds": [
145+
"opendes:master-data--Well:122"
146+
],
147+
"skippedRecordIds": []
148+
}
149+
```
126150

127151
### Get a well record
128152

129153
Get the well record data for your Azure Data Manager for Energy instance.
130154

131-
API: **Well** > **Well by ID**
132-
133155
Method: `GET`
134156

135-
:::image type="content" source="media/tutorial-wellbore-ddms/postman-api-get-well.png" alt-text="Screenshot that shows the API that gets a well record by ID." lightbox="media/tutorial-wellbore-ddms/postman-api-get-well.png":::
157+
```bash
158+
curl -X GET "https://<DNS>/api/os-wellbore-ddms/ddms/v3/wells/<well_id>" \
159+
-H "Authorization: Bearer <access_token>" \
160+
-H "data-partition-id: <data-partition-id>" \
161+
-H 'accept: application/json'
162+
```
163+
**Sample Response:**
164+
```json
165+
{
166+
"id": "opendes:master-data--Well:122",
167+
"version": 1753292228903506,
168+
"kind": "osdu:wks:master-data--Well:1.1.0",
169+
"acl": {
170+
"viewers": [
171+
"[email protected]"
172+
],
173+
"owners": [
174+
"[email protected]"
175+
]
176+
},
177+
"legal": {
178+
"legaltags": [
179+
"opendes-welltesttag"
180+
],
181+
"otherRelevantDataCountries": [
182+
"FR",
183+
"US"
184+
]
185+
},
186+
"meta": null,
187+
"data": {
188+
"ExtensionProperties": {},
189+
"FacilityName": "opendes:master-data--Well:123",
190+
"FacilityNameAliases": [
191+
{
192+
"AliasName": "20-000-00000-00",
193+
"AliasNameTypeID": "opendes:reference-data--AliasNameType:UniqueIdentifier:"
194+
}
195+
]
196+
},
197+
"createTime": "2025-07-23T17:37:09.290000+00:00",
198+
"createUser": "3046ab2b-b04c-4933-8afd-***********"
199+
}
200+
```
136201

137202
### Get well versions
138203

139204
Get the versions of each ingested well record in your Azure Data Manager for Energy instance.
140205

141-
API: **Well** > **Well Versions**
142206

143207
Method: `GET`
144208

145-
:::image type="content" source="media/tutorial-wellbore-ddms/postman-api-get-well-versions.png" alt-text="Screenshot that shows the API that gets all well versions." lightbox="media/tutorial-wellbore-ddms/postman-api-get-well-versions.png":::
209+
```bash
210+
curl -X GET "https://<DNS>/api/os-wellbore-ddms/ddms/v3/wells/<well_id>/versions" \
211+
-H "Authorization: Bearer <access_token>" \
212+
-H "data-partition-id: <data-partition-id>" \
213+
-H 'accept: application/json' \
214+
```
215+
**Sample Response:**
216+
```json
217+
{
218+
"recordId": "opendes:master-data--Well:122",
219+
"versions": [
220+
1753292228903506
221+
]
222+
}
223+
```
146224

147225
### Get a specific well version
148226

149227
Get the details of a specific version for a specific well record in your Azure Data Manager for Energy instance.
150228

151-
API: **Well** > **Well Specific Version**
152229

153230
Method: `GET`
154231

155-
:::image type="content" source="media/tutorial-wellbore-ddms/postman-api-get-specific-well-version.png" alt-text="Screenshot that shows the API that gets a specific well version." lightbox="media/tutorial-wellbore-ddms/postman-api-get-specific-well-version.png":::
232+
```bash
233+
curl -X GET "https://<DNS>/api/os-wellbore-ddms/ddms/v3/wells/<well_id>/versions/<version>" \
234+
-H "Authorization: Bearer <access_token>" \
235+
-H "data-partition-id: <data-partition-id>" \
236+
-H 'accept: application/json' \
237+
```
238+
**Sample Response:**
239+
```json
240+
{
241+
"id": "opendes:master-data--Well:122",
242+
"version": 1753292228903506,
243+
"kind": "osdu:wks:master-data--Well:1.1.0",
244+
"acl": {
245+
"viewers": [
246+
"[email protected]"
247+
],
248+
"owners": [
249+
"[email protected]"
250+
]
251+
},
252+
"legal": {
253+
"legaltags": [
254+
"opendes-welltesttag"
255+
],
256+
"otherRelevantDataCountries": [
257+
"FR",
258+
"US"
259+
]
260+
},
261+
"meta": null,
262+
"data": {
263+
"ExtensionProperties": {},
264+
"FacilityName": "opendes:master-data--Well:123",
265+
"FacilityNameAliases": [
266+
{
267+
"AliasName": "20-000-00000-00",
268+
"AliasNameTypeID": "opendes:reference-data--AliasNameType:UniqueIdentifier:"
269+
}
270+
]
271+
},
272+
"createTime": "2025-07-23T17:37:09.290000+00:00",
273+
"createUser": "3046ab2b-b04c-4933-8afd-***********"
274+
}
275+
```
156276

157277
### Delete a well record
158278

159279
Delete a specific well record from your Azure Data Manager for Energy instance.
160280

161-
API: **Clean up** > **Well Record**
162-
163281
Method: `DELETE`
164282

165-
:::image type="content" source="media/tutorial-wellbore-ddms/postman-api-delete-well.png" alt-text="Screenshot that shows the API that deletes a well record." lightbox="media/tutorial-wellbore-ddms/postman-api-delete-well.png":::
283+
```bash
284+
curl -X DELETE "https://<DNS>/api/os-wellbore-ddms/ddms/v3/wells/<well_id>" \
285+
-H "Authorization: Bearer <access_token>" \
286+
-H "data-partition-id: <data-partition-id>"
287+
```
288+
**Response code: 204 <No-content>**
166289

167290
## Next step
168291

0 commit comments

Comments
 (0)