Skip to content

Commit f2c8245

Browse files
aksjosh007aksjosh007
committed
well delivery ddms swagger
1 parent 7cabe11 commit f2c8245

File tree

1 file changed

+168
-100
lines changed

1 file changed

+168
-100
lines changed

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

Lines changed: 168 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -13,160 +13,228 @@ 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 Seismic 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:
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):
6035

61-
1. Create two JSON files on your computer by copying the data that's in the collection and environment files.
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.|
6244

63-
1. In Postman, select **Import** > **Files** > **Choose Files**, and then select the two JSON files on your computer.
6445

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
46+
## Use Well Delivery DDMS APIs to work with well data records
7847

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.
48+
### Create a legal tag
8049

50+
Create a legal tag for data compliance.
8151

82-
## Generate a token for APIs
52+
Run the following `cURL` command to create a legal tag:
8353

84-
Generate a token that you can use to work with Well Delivery DDMS APIs:
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+
```
8574

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.
75+
**Sample Response:**
76+
```json
77+
{
78+
"name": "LegalTagName",
79+
"status": "Created"
80+
}
81+
```
8782

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-
```
83+
For more information, see [Manage legal tags](how-to-manage-legal-tags.md).
9684

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":::
85+
### Add users to an entitlement group
9886

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.
87+
For users to have the proper permissions to make Petrel DDMS API calls, they must be part of the `users.datalake.admins@{data-partition-id}.dataservices.energy` entitlement group. This call adds a user to the proper group.
10088

101-
## Use Well Delivery DDMS APIs to work with well data records
89+
The user in this case is the client ID or OID in the token that's used for authentication. For example, if you generate a token by using a client ID of `8cdxxxxxxxxxxxx`, you must add `8cdxxxxxxxxxxxx` to the `users.datalake.admins` group.
90+
Follow the [Manage users](how-to-manage-users.md) guide to add appropriate entitlements for the user .
10291

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.
10492

10593
### Create a well record
10694

10795
Create a well record in your Azure Data Manager for Energy instance.
10896

109-
API: **UC1** > **entity_create well**
110-
11197
Method: `PUT`
11298

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":::
99+
```bash
100+
curl --request PUT \
101+
--url https://{base_url}/api/well-delivery/storage/v1/well \
102+
--header 'Authorization: Bearer <access_token>' \
103+
--header 'Content-Type: application/json' \
104+
--header 'data-partition-id: <data_partition_id>' \
105+
--data '{
106+
"id":"<data_partition_id>:master-data--Well:well-1753861267 434",
107+
"kind": "osdu:wks:master-data--Well:1.0.0",
108+
"acl": {
109+
"viewers": [
110+
"data.default.viewers@<data_partition_id>.dataservices.energy"
111+
],
112+
"owners": [
113+
"data.default.owners@<data_partition_id>.dataservices.energy"
114+
]
115+
},
116+
"legal": {
117+
"legaltags": [
118+
"<data_partition_id>-entity-1753861267437"
119+
],
120+
"otherRelevantDataCountries": [
121+
"US"
122+
]
123+
},
124+
"data": {
125+
"ExistenceKind": "namespace:reference-data--ExistenceKind:planned:",
126+
"FacilityName": "Well-Test"
127+
}
128+
}'
129+
```
130+
131+
**Sample Response:**
132+
```json
133+
{
134+
"created entity": "well-1753861267434:1753861269454"
135+
}
136+
```
114137

115138
### Create a wellbore record
116139

117140
Create a wellbore record in your Azure Data Manager for Energy instance.
118141

119-
API: **UC1** > **entity_create wellbore**
120-
121142
Method: `PUT`
122143

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.
128-
129-
API: **UC1** > **entity_create well Copy**
130144

131-
Method: `GET`
145+
```bash
146+
curl --request PUT \
147+
--url https://{base_url}/api/well-delivery/storage/v1/ wellbore \
148+
--header 'Authorization: Bearer <access_token>' \
149+
--header 'Content-Type: application/json' \
150+
--header 'data-partition-id: <data_partition_id>' \
151+
--data '{
152+
"id": "dp1:master-data--Wellbore:wellbore-1753861298505",
153+
"kind": "osdu:wks:master-data--Wellbore:1.0.0",
154+
"acl": {
155+
"viewers": [
156+
"data.default.viewers@<data_partition_id>.dataservices.energy"
157+
],
158+
"owners": [
159+
"data.default.owners@<data_partition_id>.dataservices.energy"
160+
]
161+
},
162+
"legal": {
163+
"legaltags": [
164+
"<data_partition_id>-entity-1753861298505"
165+
],
166+
"otherRelevantDataCountries": [
167+
"US"
168+
]
169+
},
170+
"data": {
171+
"ExistenceKind": "namespace:reference-data--ExistenceKind:planned:",
172+
"WellID": "<data_partition_id>:master-data--Well:well-1753861298505:1753861300000",
173+
"Name": "Demo wellbore name"
174+
}
175+
}'
176+
```
177+
178+
**Sample Response:**
179+
```json
180+
{
181+
"created entity": "wellbore-1753861298505:1753861301020"
182+
}
183+
```
132184

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":::
134185

135186
### Create an activity plan
136187

137188
Create an activity plan.
138189

139-
API: **UC1** > **entity_create activityplan**
140-
141190
Method: `PUT`
142191

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**
150192

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.":::
193+
```bash
194+
195+
curl --request PUT \
196+
--url https://{base_url}/api/well-delivery/storage/v1/activityplan \
197+
--header 'Authorization: Bearer <access_token>' \
198+
--header 'Content-Type: application/json' \
199+
--header 'data-partition-id: <data_partition_id>' \
200+
--data '{
201+
"id": "dp1:master-data--ActivityPlan:activityplan-1753861290577",
202+
"kind": "osdu:wks:master-data--ActivityPlan:1.0.0",
203+
"acl": {
204+
"viewers": [
205+
"data.default.viewers@<data_partition_id>.dataservices.energy"
206+
],
207+
"owners": [
208+
"data.default.owners@<data_partition_id>.dataservices.energy"
209+
]
210+
},
211+
"legal": {
212+
"legaltags": [
213+
"<data_partition_id>-entity-1753861290577"
214+
],
215+
"otherRelevantDataCountries": [
216+
"US"
217+
]
218+
},
219+
"data": {
220+
"ExistenceKind": "namespace:reference-data--ExistenceKind:planned:",
221+
"WellboreID": "<data_partition_id>:master-data--Wellbore:wellbore-1753861290577:1753861293139"
222+
}
223+
}'
224+
225+
```
226+
**Sample Response:**
227+
```json
228+
{
229+
"created entity" : "activityplan-1753861290577:1753861294109"
230+
}
231+
```
166232

167233
## Next steps
168234

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

171237
> [!div class="nextstepaction"]
172238
> [Tutorial: Work with well data records by using Wellbore DDMS APIs](tutorial-wellbore-ddms.md)
239+
240+
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)