API Reference > Part II: Authenticate using JWT > Manage data collections > Manage the delivery targets of a data collection

Manage the delivery targets of a data collection

A delivery target is a delivery option that you as a stakeholder of a data collection can use to deliver data to a Data User. Stakeholders use delivery templates to create new delivery targets for their data collections.

Create delivery targets

Use a REST API to create delivery targets in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v2/delivery-targets
Method	POST

For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the body of the API payload:

Parameter	Description	Additional Information
externalId	Optional. Enter a reference identifier for the delivery target.	If you don't specify a reference identifier, Data Marketplace automatically assigns a unique value to the item. The reference identifier that Data Marketplace automatically generates contains a prefix. The administrator can specify the prefix of the automatically generated reference identifier in Metadata Command Center. If you want to specify a reference identifier, ensure that you enter a unique value. Ensure that you don't use the prefix value that is configured in Metadata Command Center.
name	Required. Enter a name for the delivery target.	Ensure that you enter a unique value. Data Marketplace doesn't consider the letter case when it verifies the uniqueness of the name parameter's value. For example, if you try to name a delivery target as "Excel over ipfs" while a delivery target called "Excel over IPFS" already exists, the API call fails.
description	Required. Enter a description for the delivery target.	-
status	Required. Specify a status for the delivery target. The status determines whether the delivery target is available for use to the Data Users that order the data collection. Enter one of the following values: - To make the delivery targets available for use to the Data Users that order the data collection, enter ACTIVE. - To make the delivery targets unavailable for use to the Data Users that order the data collection, enter INACTIVE.	-
isDefault	Optional. Configure the delivery target as the default delivery option for a data collection. Enter one of the following values: - To configure the delivery target as the default delivery option for a data collection, enter true. - To not configure the delivery target as the default delivery option for a data collection, enter false.	-
targetSystemReference	Optional. Enter the target system or resource reference from where the data is obtained.	-
physicalLocation	Optional. Enter the location where the data is delivered to a Data User.	If the value of the managedAccess parameter is ENABLED for the delivery template that you specified in the deliveryTemplateId parameter, the data won't be delivered to the location that you specify in the physicalLocation parameter. Instead, the data will be delivered to a location that is generated at the time of order fulfillment. The generated location is unique to each order that is fulfilled using this target. For more information, see the Manage access to data with Data Access Management topic in the Set Up Data Marketplace help. For more information about how you can use APIs to manage delivery templates, see Delivery templates.
deliveryTemplateId	Required. Enter the system-generated unique identifier of the delivery template that you want to use to create the delivery target.	For more information about how you can use an API to get the system-generated unique identifier of a delivery template, see Retrieve delivery templates.
deliveryMethodId	Optional. Enter the system-generated unique identifier of a delivery method that is used in the delivery template that you specified in the deliveryTemplateId parameter.	For more information about how you can use an API to get the system-generated unique identifier of a delivery method, see Retrieve delivery methods. By default, the API uses the first delivery method that is configured for the delivery template that you specified in the deliveryTemplateId parameter.
deliveryFormatId	Optional. Enter the system-generated unique identifier of a delivery format that is used in the delivery template that you specified in the deliveryTemplateId parameter.	For more information about how you can use an API to get the system-generated unique identifier of a delivery format, see Retrieve delivery formats. By default, the API uses the first delivery format that is configured for the delivery template that you specified in the deliveryTemplateId parameter.
dataCollectionId	Required. Enter the system-generated unique identifier of the data collection for which you want to create the delivery target.	For more information about how you can use an API to get the system-generated unique identifier of a data collection, see Retrieve all data collections. To get the system-generated unique identifier of a data collection from the Data Marketplace user interface, open the data collection. The data collection page's URL contains the unique identifier. For example, in the URL https://{{CDMP_URL}}/datacollection/25158afc-3dfb-44ef-8f3e-cec1e171d0f1?dtn=&tab=summary, the unique identifier is 25158afc-3dfb-44ef-8f3e-cec1e171d0f1. Note: If the Managed Access option is enabled for the delivery template that you specified in the deliveryTemplateId parameter, ensure that the data collection that you specify in the dataCollectionId parameter is comprised only of data assets that belong to the same data source. For more information about how you can add data assets to a data collection, see Add or remove data assets from data collections.

Example request

The following example shows how you can use an API to create a delivery target:

{
"externalId": "DTG-123",
"name": "Snowflake Data Exchange - US Sales",
"description": "Snowflake Data Exchange Portal for NA Analytics references and enrichment data sources.",
"status": "ACTIVE",
"isDefault": false,
"targetSystemReference": "Snowflake",
"physicalLocation": "https://provision.snowflakecomputing.com",
"deliveryTemplateId": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"deliveryMethodId": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"deliveryFormatId": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"dataCollectionId": "b93c4539-a93e-440d-a4b4-95d69b8911e6"
}

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.

The following example shows the response of an API call to create a delivery target:

{
"id": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"externalId": "DTG-123",
"name": "Snowflake Data Exchange - US Sales",
"description": "Snowflake Data Exchange Portal for NA Analytics references and enrichment data sources.",
"isDefault": true,
"status": "ACTIVE",
"assetGroups": [
{
"id": "c1a86a0e-7690-4577-99ab-be4b193e7d90",
"name": "ASIA",
"isInherited": true
}
],
"physicalLocation": "https://provision.snowflakecomputing.com",
"targetSystemReference": "Snowflake"
}

The following table describes the parameters of each delivery target that is created:

Parameter	Description
id	System-generated unique identifier of the delivery target.
externalId	Reference identifier of the delivery target.
name	Name of the delivery target.
description	Description of the delivery target.
isDefault	Indicates whether the delivery target is the default delivery option for a data collection. This parameter can have one of the following values: - true. The delivery target is the default delivery option for a data collection. - false. The delivery target isn't the default delivery option for a data collection.
status	Status of the delivery target. Indicates whether the delivery target is available for use to the Data Users that order the data collection. A delivery target can have one of the following statuses: - ACTIVE. The delivery target is available for use. - INACTIVE. The delivery target is unavailable for use.
assetGroups	Details of the asset group that is assigned to the category that contains the data collection for the delivery target.
assetGroups > id	System-generated identifier of the asset group.
assetGroups > name	Name of the asset group.
assetGroups > isInherited	Indicates whether the asset group is directly assigned to the category or if the asset group is inherited from the category hierarchy. This parameter can have one of the following values: - true. The asset group is inherited from the category hierarchy. - false. The asset group is directly assigned to the category.
physicalLocation	The location where the data is delivered. Note: If the value of the managedAccess parameter is ENABLED, the data won't be delivered to the location that is specified in the physicalLocation parameter. Instead, the data will be delivered to a location that is generated at the time of order fulfillment. The generated location is unique to each order that is fulfilled using this target. For more information, see the Manage access to data with Data Access Management topic in the Set Up Data Marketplace help.
targetSystemReference	System where the data was delivered.

Retrieve a delivery target

Use a REST API to retrieve the details of an individual delivery target in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v2/delivery-targets/<deliveryTargetId> <deliveryTargetId>: Required. Enter the system-generated unique identifier of the delivery target that you want to modify. For more information about how you can use an API to get the system-generated unique identifier of a delivery target, see Retrieve all delivery targets.
Method	GET

For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the request query:

Parameter	Description	Additional Information
segments	Optional. Specify the type of details that you want the API request to return. Enter one or more of the following values: - all. Returns all the details about the delivery target. - deliveryTemplate. Returns the properties about the delivery template that is used to create the delivery target. - deliveryFormat. Returns the properties about the delivery format that is associated with the delivery template used to create the delivery target. - deliveryMethod. Returns the properties about the delivery method that is associated with the delivery template used to create the delivery target. - systemAttributes. Returns the details about the delivery target's creation and modification, such as the details of the user that created the delivery target, the latest user that modified the delivery target, and so on.	By default, the parameter is assigned no value and the API response includes only the basic information about the delivery target such as name, description and so on.

Note: The API has no payload.

Example request

The following example shows how you can use an API to retrieve the details of a delivery target:

https://{{CDMP_URL}}/api/v2/delivery-targets/b93c4539-a93e-440d-a4b4-95d69b8911e6

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.

The following example shows the response of an API call to retrieve the details of a delivery target:

The following table describes the parameters of the delivery target that is retrieved:

Parameter	Description
id	System-generated unique identifier of the delivery target.
externalId	Reference identifier of the delivery target.
name	Name of the delivery target.
description	Description of the delivery target.
isDefault	Indicates whether the delivery target is the default delivery option for a data collection. This parameter can have one of the following values: - true. The delivery target is the default delivery option for a data collection. - false. The delivery target isn't the default delivery option for a data collection.
status	Status of the delivery target. Indicates whether the delivery target is available for use to the Data Users that order the data collection. A delivery target can have one of the following statuses: - ACTIVE. The delivery target is available for use. - INACTIVE. The delivery target is unavailable for use.
assetGroups	Details of the asset group that is assigned to the category that contains the data collection for the delivery target.
assetGroups > id	System-generated identifier of the asset group.
assetGroups > name	Name of the asset group.
assetGroups > isInherited	Indicates whether the asset group is directly assigned to the category or if the asset group is inherited from the category hierarchy. This parameter can have one of the following values: - true. The asset group is inherited from the category hierarchy. - false. The asset group is directly assigned to the category.
physicalLocation	The location where the data is delivered. Note: If the value of the managedAccess parameter is ENABLED, the data won't be delivered to the location that is specified in the physicalLocation parameter. Instead, the data will be delivered to a location that is generated at the time of order fulfillment. The generated location is unique to each order that is fulfilled using this target. For more information, see the Manage access to data with Data Access Management topic in the Set Up Data Marketplace help.
targetSystemReference	System where the data was delivered.

Retrieve all delivery targets

Use a REST API to retrieve the details of all delivery targets in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v2/delivery-targets
Method	GET

For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the request query:

Parameter	Description	Additional Information
segments	Optional. Specify the type of details that you want the API request to return. Enter one or more of the following values: - all. Returns all the details about each delivery target that is retrieved. - deliveryTemplate. Returns the properties about the delivery template that is used to create a delivery target. - deliveryFormat. Returns the properties about the delivery format that is associated with the delivery template used to create a delivery target. - deliveryMethod. Returns the properties about the delivery method that is associated with the delivery template used to create a delivery target. - systemAttributes. Returns the details about a delivery target's creation and modification, such as the details of the user that created the delivery target, the latest user that modified the delivery target, and so on.	By default, the parameter is assigned no value and the API response includes only the basic information about the delivery target such as name, description and so on.
search	Optional. Enter the search term to find a delivery target by name.	-
offset	Optional. Specify the starting index for the paginated results.	Default value is 0.
limit	Optional. Specify the maximum number of results that are displayed on a page.	Default value is 20. Maximum value is 200.
sortby	Optional. Specify the parameters to sort the search results. Enter one of the following values: - id - name - status - createdOn - modifiedOn	Default value is modifiedOn.
sortOrder	Optional. Set the sorting order of the search results. Enter one of the following values: - To sort the search results by ascending order, enter asc. - To sort the search results by descending order, enter desc.	Default value is desc.

Note: The API has no payload.

Example request

The following example shows how you can use an API to retrieve the details of all delivery targets:

https://{{CDMP_URL}}/api/v2/delivery-targets

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.

The following example shows the response of an API call to retrieve the details of all delivery targets:

{
"pageInfo": {
"offset": 40,
"limit": 20,
"totalCount": 120
},
"links": {
"self": {
"href": "/delivery-targets?offset=40&limit=20"
},
"first": {
"href": "/delivery-targets?offset=0&limit=20"
},
"next": {
"href": "/delivery-targets?offset=60&limit=20"
},
"previous": {
"href": "/delivery-targets?offset=20&limit=20"
},
"last": {
"href": "/delivery-targets?offset=100&limit=20"
}
},
"items": [
{
"id": "b93c4539-a93e-440d-a4b4-95d69b8911e6",
"externalId": "DTG-123",
"name": "Snowflake Data Exchange - US Sales",
"description": "Snowflake Data Exchange Portal for NA Analytics references and enrichment data sources.",
"isDefault": true,
"status": "ACTIVE",
"assetGroups": [
{
"id": "c1a86a0e-7690-4577-99ab-be4b193e7d90",
"name": "ASIA",
"isInherited": true
}
],
"physicalLocation": "https://provision.snowflakecomputing.com",
"targetSystemReference": "Snowflake"
}
]
}

The following table describes the parameters of each delivery target that is retrieved:

Parameter	Description
pageInfo > offset	Starting index of the paginated results.
pageInfo > limit	The maximum number of results that are displayed on a page.
pageInfo > totalCount	Number of delivery targets retrieved.
links > self > href	The API that was invoked to generate this response.
links > first > href	The API endpoint that you can use to retrieve the search results that are displayed on the first page.
links > next > href	The API endpoint that you can use to retrieve the search results from the page following the one you currently have open.
links > previous > href	The API endpoint that you can use to retrieve the search results from the page prior to the one you currently have open.
links > last > href	The API endpoint that you can use to retrieve the search results that are displayed on the last page.
id	System-generated unique identifier of the delivery target.
externalId	Reference identifier of the delivery target.
name	Name of the delivery target.
description	Description of the delivery target.
isDefault	Indicates whether the delivery target is the default delivery option for a data collection. This parameter can have one of the following values: - true. The delivery target is the default delivery option for a data collection. - false. The delivery target isn't the default delivery option for a data collection.
status	Status of the delivery target. Indicates whether the delivery target is available for use to the Data Users that order the data collection. A delivery target can have one of the following statuses: - ACTIVE. The delivery target is available for use. - INACTIVE. The delivery target is unavailable for use.
assetGroups	Details of the asset group that is assigned to the category that contains the data collection for the delivery target.
assetGroups > id	System-generated identifier of the asset group.
assetGroups > name	Name of the asset group.
assetGroups > isInherited	Indicates whether the asset group is directly assigned to the category or if the asset group is inherited from the category hierarchy. This parameter can have one of the following values: - true. The asset group is inherited from the category hierarchy. - false. The asset group is directly assigned to the category.
physicalLocation	The location where the data is delivered. Note: If the value of the managedAccess parameter is ENABLED, the data won't be delivered to the location that is specified in the physicalLocation parameter. Instead, the data will be delivered to a location that is generated at the time of order fulfillment. The generated location is unique to each order that is fulfilled using this target. For more information, see the Manage access to data with Data Access Management topic in the Set Up Data Marketplace help.
targetSystemReference	System where the data was delivered.

Modify delivery targets

Use a REST API to modify a delivery target in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v2/delivery-targets/<deliveryTargetId> <deliveryTargetId>: Required. Enter the system generated unique identifier of the delivery target that you want to modify. For more information about how you can use an API to get the system-generated unique identifier of a delivery target, see Retrieve all delivery targets.
Method	PATCH

For more information about how you can call an API, see Authenticate using JWT.

Request

The following table describes the parameters that you enter in the body of the API payload:

Parameter	Description	Additional Information
operation	Required. Specify the type of change you want to make to the delivery target. Enter one of the following values: - To add a value to a parameter, enter add. - To replace an existing value of a parameter, enter replace. - To remove a value from a parameter, enter remove.	-
segment	Required. Specify the type of details that you want the API request to modify. Enter one of the following values: - To modify the values specified in the name and description parameters, enter summary. - To modify the value specified in the deliveryTemplateId parameter, enter deliveryTemplate. - To modify the value specified in the deliveryFormatId parameter, enter deliveryFormat. - To modify the value specified in the deliveryMethodId parameter, enter deliveryMethod. - To modify the values specified in the externalId, status, isDefault, targetSystemReference, and physicalLocation parameters, enter selfAttributes.	-
name	Optional. Enter a name for the delivery target.	Ensure that you enter a unique value. Data Marketplace doesn't consider the letter case when it verifies the uniqueness of the name parameter's value. For example, if you try to name a delivery target as "Excel over ipfs" while a delivery target called "Excel over IPFS" already exists, the API call fails.
description	Optional. Enter a description for the delivery target.	-
externalId	Optional. Enter a reference identifier for the delivery target.	If you don't specify a reference identifier, Data Marketplace automatically assigns a unique value to the item. The reference identifier that Data Marketplace automatically generates contains a prefix. The administrator can specify the prefix of the automatically generated reference identifier in Metadata Command Center. If you want to specify a reference identifier, ensure that you enter a unique value. Ensure that you don't use the prefix value that is configured in Metadata Command Center.
status	Optional. Specify a status for the delivery target. The status determines whether the delivery target is available for use to the Data Users that order the data collection. Enter one of the following values: - To make the delivery targets available for use to the Data Users that order the data collection, enter ACTIVE. - To make the delivery targets unavailable for use to the Data Users that order the data collection, enter INACTIVE.	=
isDefault	Optional. Configure the delivery target as the default delivery option for a data collection. Enter one of the following values: - To configure the delivery target as the default delivery option for a data collection, enter true. - To not configure the delivery target as the default delivery option for a data collection, enter false.	-
targetSystemReference	Optional. Enter the target system or resource reference from where the data is obtained.	-
physicalLocation	Optional. Enter the location where the data is delivered to a Data User.	If the value of the managedAccess parameter is ENABLED for the delivery template that you specified in the deliveryTemplateId parameter, the data won't be delivered to the location that you specify in the physicalLocation parameter. Instead, the data will be delivered to a location that is generated at the time of order fulfillment. The generated location is unique to each order that is fulfilled using this target. For more information, see the Manage access to data with Data Access Management topic in the Set Up Data Marketplace help. For more information about how you can use APIs to manage delivery templates, see Delivery templates.
deliveryTemplateId	Optional. Enter the system generated unique identifier of the delivery template that you want to use to for the delivery target.	For more information about how you can use an API to get the system-generated unique identifier of a delivery template, see Retrieve delivery templates.
deliveryMethodId	Optional. Enter the system generated unique identifier of the delivery method that is used in the delivery template that you specified in the deliveryTemplateId parameter.	For more information about how you can use an API to get the system-generated unique identifier of a delivery method, see Retrieve delivery methods.
deliveryFormatId	Optional. Enter the system generated unique identifier of the delivery format that is used in the delivery template that you specified in the deliveryTemplateId parameter.	For more information about how you can use an API to get the system-generated unique identifier of a delivery format, see Retrieve delivery formats.

Example request

The following example shows how you can use an API to modify a delivery target:

{
"operation": "replace",
"segment": "summary",
"value": {
"name": "Snowflake Data Exchange - US Sales",
"description": "Snowflake Data Exchange Portal for NA Analytics references and enrichment data sources."
}
}

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.

If you see the following response code, it means that the delivery target is successfully modified:

204 OK code

Delete delivery targets

Use a REST API to delete a delivery target of a data collection.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v2/delivery-targets/<deliveryTargetId> <deliveryTargetId>: Required. Enter the system-generated unique identifier of the delivery target that you want to delete. For more information about how you can use an API to get the system-generated unique identifier of a delivery target, see Retrieve all delivery targets.
Method	DELETE

For more information about how you can call an API, see Authenticate using JWT.

Request

Note: The API has no payload.

Example request

The following example shows how you can use an API to delete a delivery target:

https://{{CDMP_URL}}/api/v2/delivery-targets/67417f72-e5ab-44f0-add9-a1e412c1ce13

Response

When you invoke the API using a REST client, the client displays a response for the parameter values that you have entered.

If you see the following response code, it means that the delivery target is successfully deleted:

204 OK code