Creating Oracle Object Storage Destinations

This topic explains how to create Oracle Object Storage Destinations using the Oracle Audience Segmentation API.

In this topic:

Introduction

You can export data from Oracle Audience Segmentation into your Oracle Object Storage (OOS) by creating an Oracle Object Storage destination, and then creating an export job. This tutorial will walk through how to create an OOS destination. Using the API endpoints is currently the only method to create an Oracle Object Storage destination in Oracle Audience Segmentation .

Retrieving Oracle Object Storage Details

This section will walk through getting the Oracle Object Storage information required. To create an OOS destination, you'll need:

  1. The Destination's Unique Instance ID

  2. The Oracle Object Storage Instance URL Path

  3. The Storage Endpoint

  4. The Storage Key

  5. The Storage Secret

Destination Unique Instance ID

When creating an Oracle Object Storage destination, you must create a unique identifier for the destination. The Destination ID is displayed in the interface.

When using the APIs to create a destination, ensure the uniqueInstanceId you specify is unique.

Store Instance URL Path

An Oracle Object Storage Instance URL Path is comprised of two unique components:

s3a://<oci_bucket_name>/<folder_structure>/

  • <oci_bucket_name>

    You can find your bucket name in your Oracle Object Storage under Object Storage > Buckets.

  • <folder_structure>

    The folder path where files will be exported. For example "sample_folder".

Oracle Object Storage Endpoint

An Oracle Object Storage endpoint is comprised of two unique components:

<namespace>.compat.objectstorage.<oci_region>.oraclecloud.com

  • <namespace>

    Your Oracle Object Storage's namespace is found within in your bucket details.

  • <oci_region>

    The active region of your Oracle Object Storage. You can find your region under Infrastructure Regions (for example, "ap-hyderabad-1", "eu-frankfurt-1", "ca-toronto-1", and so on).

Oracle Object Storage Key

Your Oracle Object Storage Key is located in Oracle Object Storage under Identity & Security > Users > Customer Secret Keys.

If you don't already have a key, create a new user account.

Oracle Object Storage Secret

Your Oracle Object Storage Secret was displayed when you generated a Secret Key.

If you haven't already generated a secret key, follow the instructions below.

To generate a Secret Key:

  1. In your Oracle Object Storage navigate to Identity & Security > Users.

  2. Select the user.

  3. Under Resources click Customer Secret Keys.

  4. Enter a name for the key and click Generate Secret Key.

  5. Copy the secret key and save it for your records.

Creating Oracle Object Storage Destinations

This section will walk through how to structure the request to create the destination.

  1. Send a POST request to create a new destination.

    Request URL

    POST /api/cx-unity-api/sinkMcpsInstances

    Request body

    {
    "tenantId": <tenant_id>,
    "name": "<destination_name>",
    "description": "<destination_description>",
    "active": true,
    "componentDefinitionId": "FTPSink",
    "uniqueInstanceId": "<destination_id>",
    "parameters": {
      "path": "s3a://<bucket>/<folder>/<sub_folder>",
      "objectStoreEndpoint": "<namespace>.compat.objectstorage.<region>.oraclecloud.com",
      "objectStoreKey": "<storage_key>",
      "objectStoreSecret": "<storage_secret>",
      "fileName": "<file_name>",
      "referenceName": "<destination_id>",
      "fileFormat": "csv",
      "fileDateFormat": "yyyy-MM-dd-hh-mm-ss",
      "fileCompressionFormat": "gzip",
      "isConcurrent": "FALSE"
   }
}

    The following table provides more information about the required parameters.

    Name

    Type

    Description

    Possible values
    tenantId string Enter your MCPS tenant ID.  
    name string Enter a name for the destination.  
    description string Enter a meaningful description for the destination.  
    active boolean Whether the destination is active. Specify false to disable this destination, preventing jobs from referencing it.

    • true

    • false

    componentDefinitionId string

    Enter the destination definition. A destination definition is a template for the destination.

    For Oracle Object Storages, must be FTPSink.

    • FTPSink (Oracle Object Storages)
    uniqueInstanceId string Enter a unique ID for the destination. Refer to Destination Unique Instance ID for more information on how to retrieve this in Oracle Audience Segmentation after the destination is created.  

    Nested schema: parameters

    Name

    Type

    Description

    Possible values
    path string Location of the Oracle Object Storage. Refer to Store Instance URL Path for more information on how to retrieve this.  
    objectStoreEndpoint string The URL endpoint location of your Oracle Object Storage. Refer to Oracle Object Storage Endpoint for more information on how to retrieve this.  
    objectStoreKey string The Object Storage key of your Oracle Object Storage instance. Refer to Oracle Object Storage Key for more information on how to retrieve this.  
    objectStoreSecret string The Object Storage secret of your Oracle Object Storage instance. Refer to Oracle Object Storage Secret for more information on how to retrieve this.  
    fileName string Specify a file name to use for the exported files. The file export date will also be added to the file name during export.  
    referenceName string Must be the same value as your uniqueInstanceId. Refer to Destination Unique Instance ID for more information on how to retrieve this.  
    fileFormat string

    Whether Oracle Audience Segmentation will parse the csv files using the Opencsv parser. If the files in the FTP site are "true" CSV files (optionally quoted) set to true. If the files are delimited files where quotes are parsed as input content, set to false.

    See Opencsv file standards for more information.

    • csv

    fileDateFormat string Specify a file date format to use. By default, Oracle Audience Segmentation uses the date format "yyyy-MM-dd-hh-mm-ss-SSS".

    • yyyy-MM-dd-hh-mm-ss-SSS

    fileCompressionFormat string Specify a file compression format. If you select none, the exported file will be uncompressed and in .csv format.

    • gzip

    • none

    isConcurrent boolean Whether the export should produce a single file, or multiple files. Set to false to export into a single file, and true to export into multiple files.

    • true

    • false

    Example

    POST https://{accountUrl}/api/cx-unity-api/sinkMcpsInstances

    Sample request body

    {
  "tenantId": 100,
  "name": "OCI_Destination",
  "description": "OCI Destination for data export",
  "active": true,
  "componentDefinitionId": "FTPSink",
  "uniqueInstanceId": "destination_1",
  "parameters": {
    "path": "s3a://oci/data/",
    "objectStoreEndpoint": "nc1j2zwn3oid.compat.objectstorage.ap-hyderabad-1.oraclecloud.com",
    "objectStoreKey": "a2d2c12345d456b585df08886474ae4fb09f0d5",
    "objectStoreSecret": "NC123UdvF/EYi7ZifoV1o5geHQQuVWpRJdT1OVNaOzg=",
    "fileName": "out",
    "referenceName": "destination_1",
    "fileFormat": "csv",
    "fileDateFormat": "yyyy-MM-dd-hh-mm-ss",
    "fileCompressionFormat": "gzip",
    "isConcurrent": "FALSE"
  }
}

    Sample response

    A successful response will echo the details of the destination specified in the request, with additional properties such as the created and modified date and timestamps.

    {
  "tenantId": 100,
  "name": "OCI_Destination",
  "versionTS": 1622211746405,
  "description": "OCI Destination for data export",
  "active": true,
  "lastModifiedBy": "df5ce199266b4bdf86d9f33d10cf850a",
  "createdBy": "df5ce199266b4bdf86d9f33d10cf850a",
  "createdTS": 1622211746405,
  "componentDefinitionId": "FTPSink",
  "uniqueInstanceId": "destination_1",
  "parameters": {
    "path": "s3a://oci/data/",
    "objectStoreEndpoint": "nc1j2zwn3oid.compat.objectstorage.ap-hyderabad-1.oraclecloud.com",
    "objectStoreKey": "a2d2c12345d456b585df08886474ae4fb09f0d5",
    "objectStoreSecret": "EYi7ZifoV1o5geHQQuVWpRJdT1OVNaOzg",
    "fileName": "out",
    "referenceName": "destination_1",
    "fileFormat": "csv",
    "fileDateFormat": "yyyy-MM-dd-hh-mm-ss",
    "fileCompressionFormat": "gzip",
    "isConcurrent": "FALSE"
  }
}

  2. Next you can create an export job to use your new destination.

Learn more

Destinations API

Creating Oracle Object Storage Sources