Edit

Tutorial: Work with Petrel data records by using Petrel DDMS APIs

  • Article

Use Petrel Domain Data Management Services (Petrel DDMS) APIs in Postman to work with Petrel data in your instance of Azure Data Manager for Energy.

In this tutorial, you'll learn how to:

  • Set up Postman to use a Petrel DDMS collection.
  • Set up Postman to use a Petrel DDMS environment.
  • Send requests via Postman.
  • Generate an authorization token.
  • Use Petrel DDMS APIs to work with Petrel data records/projects.

For more information about DDMS, see DDMS concepts.

Prerequisites

Get your Azure Data Manager for Energy instance details

The first step is to get the following information from your Azure Data Manager for Energy instance in the Azure portal:

Parameter Value Example
CLIENT_ID Application (client) ID 3dfxxxxxxxxxxxxxxxxxxxxxx
CLIENT_SECRET Client secrets _fl******************
TENANT_ID Directory (tenant) ID 72fxxxxxxxxxxxx
SCOPE Application (client) ID 3dfxxxxxxxxxxxxxxxxxxxxxxx
HOSTNAME URI <instance>.energy.azure.com
DATA_PARTITION_ID Data Partition(s) <instance>-<data-partition-name>

You'll use this information later in the tutorial.

Set up Postman

Next, set up Postman:

  1. Download and install the Postman desktop app.

  2. Import the following files in Postman:

  3. Create a Postman environment using the values you obtained above. The environment should look something like this:

    Screenshot that shows pdsv2 env.

Generate a token to use in APIs

The Postman collection for Petrel DDMS contains requests you can use to interact with your Petrel Projects. It also contains a request to query current Petrel projects and records in your Azure Data Manager for Energy instance.

  1. In Postman, in the left menu, select Collections, and then select Petrel DDMS. Under Setup, select Get Token.

  2. In the environment dropdown in the upper-right corner, select Petrel DDMS Environment you created.

  3. To send the request, select Send.

This request will generate an access token and assign it as the authorization method for future requests.

You can also generate a token by using the cURL command in Postman or a terminal to generate a bearer token. Use the values from your Azure Data Manager for Energy instance.

      curl --location --request POST 'https://login.microsoftonline.com/{{TENANT_ID}}/oauth2/v2.0/token' \
          --header 'Content-Type: application/x-www-form-urlencoded' \
          --data-urlencode 'grant_type=client_credentials' \
          --data-urlencode 'client_id={{CLIENT_ID}}' \
          --data-urlencode 'client_secret={{CLIENT_SECRET}}' \
          --data-urlencode 'scope={{SCOPE}}'

In order to use this cURL generated token, you must update access_token in your Collection variables with the value after Bearer in the response.

Use Petrel DDMS APIs to work with Petrel Projects

Successfully completing the Postman requests described in the following Petrel DDMS API allows you to interact with your save Petrel projects. While the API does provide a means of uploading data, we recommended that you upload your projects via the DELFI Petrel Explorer. All of the following API calls assume you have a project uploaded to Petrel Explorer.

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

API: Setup > Create Legal Tag for PDS

Method: POST

Screenshot that shows the API that creates a legal tag.

For more information, see Manage legal tags.

Add User to Entitlement Groups

In order to ensure the user has the proper permissions to make the Petrel DDMS API calls, the user must be apart of the users.datalake.admins@{data-partition-id}.dataservices.energy entitlements group. This call adds the user to the proper groups.

The USER in this case is the Client ID/OID contained in the token used for authentication. For example, if you generate a token using a client ID of 8cdxxxxxxxxxxxx, you must add 8cdxxxxxxxxxxxx to the users.datalake.admins group.

API: Setup > Add User to DATALAKE Admins

Method: POST

Screenshot that shows the API that adds user to entitlements.

Get Project

Given a Project ID, returns the corresponding Petrel Project record in your Azure Data Manager for Energy instance.

API: Project > Get Project.

Method: GET

Screenshot that shows the API that gets a project.

Delete Project

Given a Project ID, deletes the project and the associated Petrel Project record data in your Azure Data Manager for Energy instance.

API: Project > Delete Project

Method: DELETE

Screenshot that shows the API that deletes a project.

Get Project Version

Given a Project ID and a Version ID, gets the Petrel Version record associated with that project/version ID in your Azure Data Manager for Energy instance.

API: Project > Project Version

Method: GET

Screenshot that shows the API that gets project version.

Get a Project Download URL

Given a Project ID, returns a SAS URL to download the data of the corresponding project from your Azure Data Manager for Energy instance.

API: Project > Download URL

Method: GET

Screenshot that shows the API that gets download SAS URL.

Get a Project Upload URL

Given a Project ID, returns two SAS URLs. One to upload data to and one to download data from the corresponding project in your Azure Data Manager for Energy instance.

API: Project > Upload URL

Method: POST

Screenshot that shows the API that gets upload SAS URL.

Using the Upload URL

Once you have your SAS upload url, it should look something like this:

https://{storage-account}.z15.blob.storage.azure.net/projects/{data-partition-id}/{projectID}.staging/{versionID}?{SAS-token-info}

Next you can modify this URL to contain the filename of data you want to upload:

https://{storage-account}.z15.blob.storage.azure.net/projects/{data-partition-id}/{projectID}.staging/{versionID}/{FILENAME}?{SAS-token-info}

Making a PUT call to this URL uploads the contents of the body to the blob storage under the FILENAME provided.

Update Project

Given a Project ID, SAS upload URL, and a Petrel Project record, updates the Petrel Project record in your Azure Data Manager for Energy with the new values provided. Can also upload data to a given project but doesn't have to.

API: Project > Update Project

Method: PUT

Screenshot that shows the API that updates project.

Search Projects

Allows the user to search through Petrel Projects given many fields. The call returns all match Project IDs. The API supports full text search on string fields, range queries on date, numeric or string fields, along with geo-spatial search.

API: Project > Search Projects

Method: POST

Screenshot that shows the API that deletes a well record.

Next Steps

Visit the following DELFI links for further tutorials involving Petrel Explorer and Petrel Workflows:
Get started with Project Explorer (slb.com)
Open a project saved in Project Explorer (slb.com)
Upload ZGY data from Petrel to the DELFI Data Ecosystem (slb.com)
Import ZGY data from the DELFI Data Ecosystem to Petrel (slb.com)
Save a Petrel project in Project Explorer (slb.com)