Edit

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

  • Article

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

In this tutorial, you 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 and 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 partitions <instance>-<data-partition-name>

You'll use this information later in the tutorial.

Set up Postman

  1. Download and install the Postman desktop app.

  2. Import the following file in Postman: Petrel DDMS Postman collection.

  3. Create a Postman environment by using the values that you obtained earlier. The environment should look something like this example:

    Screenshot that shows an example Postman environment.

Generate a token to use in APIs

The Postman collection for Petrel DDMS contains requests that 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, on the left menu, select Collections, and then select Petrel DDMS. Under Setup, select Get Token.

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

  3. To send the request, select Send.

This request generates an access token and assigns 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}}'

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 that are described in the following Petrel DDMS APIs indicates successful interaction with your saved Petrel projects. Although the API provides a way to upload data, we recommend that you upload your projects via DELFI Petrel Project Explorer. All of the following API calls assume that you have a project uploaded to Petrel Project 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 users to an entitlement group

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.

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.

API: Setup > Add User to DATALAKE Admins

Method: POST

Screenshot that shows the API that adds user to entitlements.

Get a project

Use a project ID to return 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 a project

Use a project ID to delete a 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 a project version

Use a project ID and a version ID to get the Petrel version record that's associated with the project and version in your Azure Data Manager for Energy instance.

API: Project > Get Project Version

Method: GET

Screenshot that shows the API that gets a project version.

Get a project download URL

Use a project ID to get a shared access signature (SAS) URL so you can download the data of the corresponding project from your Azure Data Manager for Energy instance.

API: Project > Get Project Download

Method: GET

Screenshot that shows the API that gets a project download URL.

Get a project upload URL

Use a project ID to get two SAS URLs. One URL uploads data to the corresponding project in your Azure Data Manager for Energy instance. The other URL downloads data from the corresponding project in your Azure Data Manager for Energy instance.

API: Project > Get Signed Upload URL

Method: POST

Screenshot that shows the API that gets a project upload URL.

Your SAS upload URL should look something like this example:

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

You can modify this URL to contain the file name of data that 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 body to the blob storage under the provided FILENAME value.

Update a project

Use a project ID and a SAS upload URL to update a Petrel project record in Azure Data Manager for Energy with the new values. You can also upload data to a project if you want.

API: Project > Update Project

Method: PUT

Screenshot that shows the API that updates a project.

Search through projects

You can search through Petrel projects by using many fields. The call returns all matching project IDs. The API supports:

  • Full-text search on string fields.
  • Range queries based on date, numeric, or string fields.
  • Geospatial search.

API: Project > Search Projects

Method: POST

Screenshot that shows the API that deletes a well record.

Related content

Use the following DELFI links to read other tutorials that involve Petrel Project Explorer and Petrel workflows: