Edit

Share via

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

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

In this tutorial, you learn to :

  • 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 details for the Azure Data Manager for Energy instance

For this tutorial, you need the following parameters:

Parameter Value to use Example Where to find this value
DNS URI <instance>.energy.azure.com Find this value on the overview page of the Azure Data Manager for Energy instance.
data-partition-id Data partition <data-partition-id> Find this value on the Data Partition section within the Azure Data Manager for Energy instance.
access_token Access token value 0.ATcA01-XWHdJ0ES-qDevC6r........... Follow How to generate auth token to create an access token and save it.

Follow the Manage users guide to add appropriate entitlements for the user who's running this tutorial.

Set up your environment

Ensure you have cURL installed on your system to make API calls.

Use Petrel DDMS APIs to work with Petrel projects

Successfully completing the API calls that are present in swagger indicates successful interaction with your saved Petrel projects. Although the API provides a way to upload data, we recommend uploading 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 you can use for data compliance.

Run the following cURL command to create a legal tag:

curl -X POST "https://<DNS>/api/legal/v1/legaltags" \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -H "data-partition-id: <data-partition-id>" \
     -d '{
           "name": "LegalTagName",
           "description": "Legal Tag added for Well",
           "properties": {
               "contractId": "123456",
               "countryOfOrigin": ["US", "CA"],
               "dataType": "Third Party Data",
               "exportClassification": "EAR99",
               "originator": "xyz",
               "personalData": "No Personal Data",
               "securityClassification": "Private",
               "expirationDate": "2025-12-25"
           }
       }'

Sample Response:

{
  "name": "LegalTagName",
  "status": "Created"
}

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. Follow the Manage users guide to add appropriate entitlements for the user .

Get a project

Use a project ID to return the corresponding Petrel project record in your Azure Data Manager for Energy instance.

API

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

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

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

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

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

Search through projects

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

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

API

Related content

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