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

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:

For more information about DDMS, see DDMS concepts.

Prerequisites

• An Azure subscription
• An instance of Azure Data Manager for Energy created in your Azure subscription

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:

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:

   

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

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

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

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

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

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

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

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

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

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

Related content

Use the following DELFI links to read other tutorials that involve Petrel Project 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)