Prerequisites

Ensure you complete all the required prerequisites before you use Oracle Analytics Cloud REST APIs.

  • Snapshot REST API - Prerequisites for Resource Principal Authentication
  • Snapshot REST API - Prerequisites for User Principal Authentication (Deprecated)

Snapshot REST API - Prerequisites for Resource Principal Authentication

Before you can use the snapshot REST API, you must complete several prerequisite tasks in Oracle Cloud Infrastructure (OCI) so Oracle Analytics Cloud has access to a bucket for snapshot storage. Oracle recommends that you use resource principal authentication to authorize access to snapshot storage:

  • Create a bucket in OCI Object Storage that's suitable for storing snapshots for your Oracle Analytics Cloud instance.
  • Create an OCI IAM policy that enables your Oracle Analytics Cloud instance to access the storage bucket using resource principal authentication.
After setting up the resource principal for your Oracle Analytics Cloud instance, you can use the Create a snapshot endpoint with the auth type parameter set to OCI_RESOURCE_PRINCIPAL.

Note:

The prerequisites for user principal authentication (using an API signing key) are different. See Snapshot REST API - Prerequisites for User Principal Authentication.

Create a Bucket for Storing Snapshots

First, create a private bucket in Object Storage for your snapshots. The bucket must be in the same region and tenancy as your Oracle Analytics Cloud instance.

For information on the required permissions to create a bucket in Object Storage, see Required IAM Policy.

  1. Ensure you have access to Oracle Cloud Infrastructure (OCI) Object Storage and permissions to create a bucket where you can store snapshots. Specifically, you need the following permissions on the storage bucket where the snapshots are stored:
    • OBJECT_CREATE
    • OBJECT_OVERWRITE
  2. In Oracle Cloud Infrastructure Console, navigate to Object Storage & Archive Storage.

    You must have access to OCI Object Storage and permissions to create a bucket where you want to store snapshots.

  3. Under Object Storage & Archive Storage, click Buckets.
  4. Select the required compartment.
  5. Create a private bucket for snapshots. Click Create Bucket.

    Buckets are private by default.

Give Oracle Analytics Cloud Access to the Storage Bucket

Next, create an OCI IAM policy that gives your Oracle Analytics Cloud instance read and write access to the storage bucket using resource principal authentication. You create policies using the Oracle Cloud Infrastructure Console. For detailed information, see Managing Policies.

  1. In Oracle Cloud Infrastructure Console, navigate to Identity & Security. Under Identity, click Policies.
  2. Click Create Policy.
  3. Enter a name for the policy and the policy statement.

    For guidance, refer to the sample policies below.

Sample IAM Policies for Resource Principal Authentication

Here are typical policy statements that you might use to authorize your Oracle Analytics Cloud instance to access the bucket you create for snapshot storage using resource principal.

Note:

Oracle Analytics Cloud uses OCI Object Storage for several reasons, for example to store snapshots, source files for datasets, and as a delivery location for pixel-perfect reports. These sample IAM policies give your Oracle Analytics Cloud manage permissions on the bucket you want to use for snapshot storage. However, it's important to remember that when you give your instance access to Object Storage using a resource principal, all the features in your Oracle Analytics Cloud instance that integrate with Object Storage using a resource principal have the same access, not just the snapshot REST API.
Allow a specific OAC instance to access any storage bucket in the tenancy

  • Allow any-user TO manage objects IN tenancy where request.principal.id='ocid1.analyticsinstancedev.oc1.iad.test.aaaaaaaabbbbbbbbccccccccddddddddeeeeeeeeffffffffgggggggghhhh'

Allow a specific OAC instance to access any storage buckets in a specific compartment

  • Allow any-user TO manage objects IN compartment myOAC-compartment where request.principal.id='ocid1.analyticsinstancedev.oc1.iad.test.aaaaaaaabbbbbbbbccccccccddddddddeeeeeeeeffffffffgggggggghhhh'

Allow a specific OAC instance to access a specific storage bucket in a specific compartment

  • Allow any-user TO manage objects IN compartment myOAC-compartment where all {request.principal.id='ocid1.analyticsinstancedev.oc1.iad.test.aaaaaaaabbbbbbbbccccccccddddddddeeeeeeeeffffffffgggggggghhhh', target.bucket.name = 'myOAC-snapshot-bucket'}

Allow a specific OAC instance to access a specific folder in a specific storage bucket in a specific compartment

  • Allow any-user TO manage objects IN compartment myOAC-compartment where all {request.principal.id='ocid1.analyticsinstancedev.oc1.iad.test.aaaaaaaabbbbbbbbccccccccddddddddeeeeeeeeffffffffgggggggghhhh', target.bucket.name = 'myOAC-snapshot-bucket', target.object.name = 'myOACsnapshots/*'}

Snapshot REST API - Prerequisites for User Principal Authentication (Deprecated)

(Deprecated from November 2024) The prerequisite tasks for user principal authentication (using an API signing key) are different:

  • Ensure you have access to Oracle Cloud Infrastructure (OCI) Object Storage and permissions to create a bucket where you can store snapshots. Specifically, you need the following permissions on the storage bucket where the snapshots are stored:
    • OBJECT_CREATE
    • OBJECT_OVERWRITE

  • Generate an Oracle Cloud Infrastructure API signing key that authorizes you (or another user) to access OCI Object Storage where snapshots are stored. See How to Generate an API Signing Key.

    You must pass this signing key in the payload for some snapshot APIs. Before you add it to the payload, you must Base64 encode the private key (ociPrivateKeyWrapped). For example, to generate a Base64 encoded string from your private key:

    On Mac: cat myprivate-key.pem | base64 -o mywrapped-private-key.pem

    On Linux: cat myprivate-key.pem | base64 -w 0 > mywrapped-private-key.pem

    Note: Ensure that the private key file that you encode includes -----BEGIN and -----END tags.

  • Obtain additional information required to access OCI Object Storage. For example, the region, tenancy Oracle Cloud ID (OCID), and user OCID. See Where to Get the Tenancy's OCID and User's OCID.

After setting up the user principal for your Oracle Analytics Cloud instance, you can use the Create a snapshot endpoint with the auth type parameter set to OSS_AUTH_OCI_USER_ID.