1. Using Oracle Autonomous Database Serverless
  2. Tasks
  3. Data Sharing
  4. Share Data with Data Studio
  5. The Data Share Tool

The Data Share Tool

The Data Share tool allows you to share data and metadata with other users. The Data Share page displays information about the different types of shares available in the Oracle Autonomous Database.

Select the Data Share menu from the Data Studio suite in the Database Actions homepage to access this tool. This opens the Data Share homepage. It consists of widgets that enable you to provide and consume share objects.

Note:

If you do not see the Share tool card then your database user is missing the required DWROLE role.

The widgets are defined in the following sections:

Note:

You must have the correct privileges to create or consume a data share. In case the Data Share card is disabled, click on the tool tip and follow the steps for the administrator to grant you the required privilege.

The following topics describe the Data Share page and how to use it:

Parent topic: Share Data with Data Studio

Overview of the Data Share Tool

Here is an overview of the Data Share tool.

Share Terminology

Provider: The Autonomous Database Serverless enables the provider to share existing objects. The share can contain a single table, a set of related tables, or a set of tables with some logical grouping. It could be a person, an institution, or a software system that shares the objects.

Example: An institution, such as NASA, that makes a data set available via data.gov.

Recipient: A Share recipient is an entity that associates an individual, an institution or a software system that receives a share from a provider. A recipient can have access to multiple shares. If you remove a recipient, that recipient loses access to all shares it could previously access.

Example: An external system, such as Microsoft Power BI, that supports the Delta Sharing REST API.

Share: A Share is a named entity in the provider’s instance. It can be a group of datasets shared as a single entity.

Example: A SALES table that needs to be shared within an organization.

Overview of Providers and Recipients

A Data Share is the logical container that contains objects (such as tables) that share recipients will get access to a share and all tables within this share. A Data Share also implements security mechanisms on a high object level which simplifies the authorization for a set of individual objects. A provider creates and publishes share of a versioned type. The recipient is given access to a share. The provider can modify shares (both data and metadata) after the provider publishes the share to the recipients.

Use Case of Data Share

A marketing agency can share sales information with multiple interested parties. The Data Analysis tool analyses the data, generates insights and then the application shares the information with interested parties.

How the Data Share tool works?

Data is made accessible by the data sharing provider (that is an Oracle Autonomous Database) to the data sharing recipient (For example, Microsoft Power BI) at query time in parquet format. The provider can only share data which they have access to when they log into an autonomous database instance.

As a data provider, you create a share and select other additional entities to share. The Oracle Data Sharing for general recipients is based on the open delta sharing standard protocol, providing a simple REST-based API to share data in parquet format.

The Autonomous Database Serverless Sharing protocol works as follows:

  • The provider creates and publishes a share that can be shared with one or multiple recipients. Every recipient will get a personal activation link to download their own JSON profile with the necessary information to access their share.
  • The recipient registers with the share server by entering the URL for the end point along with a client ID, secret key and a bearer token.
  • The recipient retrieves data from the share by calling the /shares/../tables/../query endpoint to obtain a list of URLs. The recipient then sends a GET request on these URLs to obtain the parquet files.

Features of Autonomous Database Serverless Share

With Autonomous Database Share you can:
  • Share objects easily across Autonomous Databases and all tools or APIs that support the open delta sharing protocol.
  • Share versioned data with many recipients without data replication for all recipients.
  • Establish secure and centrally managed data sharing and collaboration within and across organizations.

Share Architecture

The following diagram is a generalized flow diagram of the architecture of the Data Share.Description of reference-architecture.png follows
Description of the illustration reference-architecture.png

Prerequisites for Share Providers

Here are some prerequisites for a share provider to use the share tool:

  • You must have read and write access to a bucket to store or cache your shares.
  • The schema you wish to use to create and publish shares must be enabled by an ADMIN user.

Prerequisites for Share Recipients

The share recipient must have a valid email address a provider can use to register the recipient to use the share tool. Oracle Data Share allows to share the information about a recipient's activation link by email.

Share Publication

The Data Share offers the following type of share:

  • Versioned Share: In this type of share, data is shared and published as well-defined, known, as-of-snapshots. At the time of publication, the tool generates and stores the data share as parquet files in the specified bucket. Any properly authenticated data recipient is able to directly access the share in the object store.

Parent topic: The Data Share Tool

Access the Data Share Tool

Support for Data Sharing is not automatically enabled in Database Actions in Limited Availability.

You must enable Data Sharing by performing these prerequisites. Data Share is part of the Data Studio suite of tools built into Oracle Autonomous Database. You must access Database Actions as an ADMIN.

Enable Schema

To enable the schema, run the following code as ADMIN user:
begin
  -- ENABLE DATA SHARING
    DBMS_SHARE.ENABLE_SCHEMA(
            SCHEMA_NAME => 'ADMIN',
            ENABLED => TRUE
    );
    commit;
end;

To access the Data Share tool:

  1. Run the following code as ADMIN user, to enable the ADMIN schema for data sharing. This privilege is required for any user that wants to use data sharing.
    begin
  -- ENABLE DATA SHARING
    DBMS_SHARE.ENABLE_SCHEMA(
            SCHEMA_NAME => 'ADMIN',
            ENABLED => TRUE
    );
    commit;
end;
  2. Navigate to the Database Actions Launchpad on your Autonomous Database instance.
  3. Select the Data Share tile, under Data Studio.
  4. When you login to the Data Share home page, you can view Provide Share and Consume Share widgets under Provider and Consumer. Select Provide Share to create a share and select the Consume Share widget to subscribe to a share provider. For more details on the instructions refer to the Provide Share and Consume Share sections of the document.Description of data-share-homepage.png follows
    Description of the illustration data-share-homepage.png
  5. Select the Quick Start Guide icon to view step by step how to's on using the Oracle Autonomous Database as a data share provider and a data share recipient. Here is the link to the Quick Start Guide.
  6. You can view share usage report on your users to help you understand how the share tool is being used. These are the reports you will see in the Data Share home page and are constructed using the inputs provided to the Data Share tool.
    • Top 3 activity by Recipient: Shows information about top three activities sorted by recipient.
    • Top 3 accessed Shares: Shows information about the top three shares accessed with their respective recipient.
    • Top 3 accessed Tables: Shows information about the top three tables along with the number of people who have utilized them.

Parent topic: The Data Share Tool

Working with Share

Oracle Autonomous Database enables you to create shares using the share tool.

Sharing objects requires two roles. The Provider provides data share for access and the Consumer role consumes (or receives) access to the published shares. The provider creates a share with the objects to share in the desired cloud object location. The provider also adds the recipient. The recipient accepts and receives the configured shared objects from the provider for consumption.

  • Provide Share
    Use the Provide Share page to view the number of shares, the number of share recipients, search for a share entity, search for a recipient, create a new share and create a new recipient.
  • Create Share
    Use the Data Share tool to create a new share. This section describes the steps to share data with other systems.
  • View Share Entity Details
    To view details about an entity, click the Actions icon at the right of the Share entity entry, then click View Details.
  • Create Share Recipient
    On the Provide Shares page, click the Recipients widget and select + Create Recipient to create a new Share Recipient.
  • View Share Recipient Entity Details
    Click the Actions icon at the right of the Share Recipient entity entry, then click View Details.
  • Consume Share
    Once the providers share the objects, there are a few steps the recipients need to follow to consume the share.
  • About the JSON Profile
    In the previous sections we have learned to create share objects, configure the publication and share the activation mail with the profile link to the recipient.
  • Subscribe to Share Provider
    You can subscribe to a share provider and enable access of the objects the provider shares with the recipients.
  • View Share Provider Entity Details
    To view details about the Share Provider entity, click the Actions icon at the right of the Share Provider entity entry, then click View Details.
  • FAQs on the Data Share Tool
    The following are frequently asked questions on the Data Share tool.

Parent topic: The Data Share Tool

Provide Share

Use the Provide Share page to view the number of shares, the number of share recipients, search for a share entity, search for a recipient, create a new share and create a new recipient.

The Provide share page enables you to view, create, edit and access information on the shares and recipients you create from this page. Click the Provide Share menu under Data Share in the Data Studio menu to reach the Provide Share page. You can switch the display of the Provide Share screen based on the widget you select from the Shares and Recipients section.

The following image displays the Provide Share page when you select the SHARES widget.Description of provide-share-new.png follows
Description of the illustration provide-share-new.png

The Provide Share page when you select the Shares widget consists of the following:
  1. The top section of the Provide Share page displays Shares and Recipients section with two widgets. The widgets are defined in the following sections:
    • SHARES- Select this widget to view, search and perform actions on the Shares you create.
    • RECIPIENTS- Select this widget to view, search and perform actions on the Share Recipients you create.
  2. Search Shares field

    Selecting Shares widget enables you to search for the share you create. You can click the field and type or paste the name of the share or the recipient you are looking for. Click the magnifier icon to return the search input. Click X to clear your searches in the Search Shares field.

  3. Create Share button

    You can create a new share and a new recipient from this button. Refer to the Create Share and Create Share Recipients section to explore more on what each button does.

  4. Toolbar

    The toolbar consists of the following buttons:

    • Sort By

      To select sorting values, click the Sort By button to open the list of options. Then click the Ascending or Descending icon next to one or more of the sorting values.

      For example, if you select the Ascending icon next to Entity name and the Descending icon next to Entity type, the entities will be sorted in alphabetical order by entity name and then in reverse alphabetical order by entity type.

      Click Reset in the list to clear the choices in the list.

      The sorting values you choose are listed next to the Sort by label beneath the toolbar. Click the X icon on a sorting value to remove it.

    • Page size

      By default, up to 25 entities are displayed on the page. If you want more entities on a page, select a number from this list.

    • Previous and Next

      If the search results are displayed on multiple pages, click these buttons to navigate through the pages.

    • Refresh

      Click to refresh the entities shown on the page, based on the current search string.

    • Entity view options

      Choose one of these three options to set how entities are displayed on the page.

      Click Open Card view to display entities as card arranged into one or two columns; click Open Grid Viewto display entities as rows in a table; or click Open List View to display entities in a single column of panels.
  5. Sort by settings

    When you set sorting values by using the Sort By control in the toolbar, the settings are displayed in small boxes beneath the toolbar. You can delete a setting by clicking the X icon in the box. Or you can change the settings by returning to the Sort By control in the toolbar.

  6. Display area

    The area below the Search field displays the entities returned by a search. If you select the Shares widget, you will view the Share entities in the display area. If you select the Recipient widget, you will view the Share Recipient entities in the display area.

The following image displays the Provide Share page when you select the RECIPIENTS widget.Description of provide-share-recipients-new.png follows
Description of the illustration provide-share-recipients-new.png

The search field and the display area of the page varies when you switch between the SHARES and RECIPIENTS widgets.

The Provide Share page consists of the following:
  1. The top section of the Provide Share page displays Shares and Recipients section with two widgets. The widgets are defined in the following sections:
    • SHARES- Select this widget to view, search and perform actions on the Shares you create.
    • RECIPIENTS- Select this widget to view, search and perform actions on the Share Recipients you create.
  2. Search Recipients field

    Searching for a share or recipient depends on the widget you select from the Shares and Recipients section. If you select the Recipients widget, you can search for the recipients you create. You can click the field and type or paste the name of the share or the recipient you are looking for. Click the magnifier icon to return the search input. Click X to clear your searches in the Search Shares or Search Recipients field.

  3. + Create Recipient button

    You can create a new share and a new recipient from this button. Refer to the Create Share and Create Recipients section to explore more on what each button does.

  4. Toolbar

    The toolbar consists of the following buttons:

    • Sort By

      To select sorting values, click the Sort By button to open the list of options. Then click the Ascending or Descending icon next to one or more of the sorting values.

      For example, if you select the Ascending icon next to Entity name and the Descending icon next to Entity type, the entities will be sorted in alphabetical order by entity name and then in reverse alphabetical order by entity type.

      Click Resetin the list to clear the choices in the list.

      The sorting values you choose are listed next to the Sort by label beneath the toolbar. Click the X icon on a sorting value to remove it.

    • Page size

      By default, up to 25 entities are displayed on the page. If you want more entities on a page, select a number from this list.

    • Previous and Next

      If the search results are displayed on multiple pages, click these buttons to navigate through the pages.

    • Refresh

      Click to refresh the entities shown on the page, based on the current search string.

    • Entity view options

      Choose one of these three options to set how entities are displayed on the page.

      Click Open Card viewto display entities as card arranged into one or two columns; click Open Grid Viewto display entities as rows in a table; or click Open List View to display entities in a single column of panels.
  5. Sort by settings

    When you set sorting values by using the Sort By control in the toolbar, the settings are displayed in small boxes beneath the toolbar. You can delete a setting by clicking the X icon in the box. Or you can change the settings by returning to the Sort By control in the toolbar.

  6. Display area

    The area below the Search field displays the entities returned by a search. If you select the Shares widget, you will view the Share entities in the display area. If you select the Recipient widget, you will view the Share Recipient entities in the display area.

Parent topic: Working with Share

Create Share

Use the Data Share tool to create a new share. This section describes the steps to share data with other systems.

This section describes how to:
  • Create a Share.
  • Enter the details of publication, such as storage details.
  • Add objects to your share.
  • Enable a schedule for your share.
  • Add recipients to your share.

On the Provide Share page, select + Create Share from the Create menu. This brings up the Create Share wizard.

  1. On the Create Share wizard, in the Name field of the General tab, enter a name for the Share. For example: My_Share.

    In the Description field, enter a description for the link. For example: Weekly Sales report.

    Select Next to progress to the Publish Details tab of the Create Share wizard. You can alternatively click on the Publish Details tab to progress to the Publish Details screen of the wizard.

    Description of create-share-general.png follows
    Description of the illustration create-share-general.png
  2. In the Publish Details Tables tab of the wizard, select SHARE VERSIONS USING OBJECT STORAGE. Description of create-share-publish-details.png follows
    Description of the illustration create-share-publish-details.png
    Select a cloud location where you want the share to be published. If you already have an OCI cloud storage location available, use the Select Cloud location drop-down and select any available Cloud location from the drop-down. You will view a successful message if you have access to read, write, or delete in that cloud location.

    Note:

    Select Create Cloud location and follow the steps described in the Create Oracle Cloud Infrastructure Native Credentials if you do not have a cloud location available.

    For sharing versioned data, you can enable the schedule for share. Select Enable For Scheduling option to set up a schedule for sharing. In the time interval fields, enter a number, and select a time type and the days on which to poll the bucket for new or changed files. For example, to poll every two hours on Monday, Wednesday, and Friday, enter 2, select Hours, and then select Monday, Wednesday, Friday in the appropriate fields. You can select All Days, Monday to Friday, Sunday to Thursday, or Custom from the Week Days drop-down. The Custom field enables you to select Monday, Tuesday, Wednesday, Thursday and Friday in the appropriate fields.

    Select a start and end date. If you don't select a start date, the current time and date are used as the start date. The end date is optional. However, without an end date, the share will continue to poll. This is an optional step.

    Click Next to progress to the Select Tables tab of the Create Share wizard.

  3. On the Select Tables tab of the wizard, select the schema from the drop-down menu and click the table you wish to share from the Available Tables. Choose any of the available options:
    • >: This option enables you to move the table to Shared Tables.
    • <: To remove the selected table from Shared Tables select this option.
    • >>: This option allows you to move all the tables to the Shared Tables screen.
    • <<: To remove all the selected tables from Shared Tables select this option.
    Description of create-share-select-tables.png follows
    Description of the illustration create-share-select-tables.png
    Click Next to proceed to the Recipients tab of the Create Share wizard.

    Note:

    You may find it convenient to click on the specific tab to move back and forth. You can update changes on any screen this way.
  4. On the Recipients tab of the Create Share wizard, select available Recipients from the drop-down. The list of recipients available in the drop-down depends on the scope of the share. You can select any or all the following values depending on with whom you intend to share the data:
    • MY_REGION: Access to the data share is allowed for databases in the same region as the data share provider.
    • MY_TENANCY: Access to the data share is allowed for databases in the same tenancy as the data share provider.
    • MY_COMPARTMENT: Access to the data share is allowed for databases in the same compartment as the data share provider.Description of recipients-tab.png follows
      Description of the illustration recipients-tab.png
  5. In case you want to create a new recipient, select New Recipient. Selecting New Recipient opens a Create Share Recipient wizard. Enter the recipient's Name, Description (optional) and Email in their respective fields.

    Note:

    Ensure there are no spaces in the name of the recipient. This field does not support duplicate recipient names. If you try creating a recipient with a duplicate name, the creation of the share fails with the "Name is already used by an existing object" error.
    Description of create-share-recipient.png follows
    Description of the illustration create-share-recipient.png

    Click Create to finish creating the share recipient. The newly added recipient is displayed in the list of recipients. Click Cancel to cancel the ongoing process of recipient creation.

  6. After you create a new share recipient, in the granted recipient's list you can:
    • Select copy profile activation link to clipboard icon to copy the activation link.
    • Select Email recipient profile download link icon to mail the profile link to the recipient you select in this step. Once you select it, the Share tool triggers an activation mail with the profile link to the recipient’s email address. Click Send to share the profile link with the recipient. See About the Consume Share Page to know more about the activation mail and how to proceed as a recipient once you receive the activation mail.
    • Click deselect Recipient icon to remove the selected recipient.Description of new-recipient.png follows
      Description of the illustration new-recipient.png

    Select Create to create the share. You will receive a successful share notification message at the top right of the display that says the share is successful.

After share is created, you can view the new Share entity in the Provide Share page.

Click the name of the entity or click Action to view details about the share entity. See View Share Entity Details.

Parent topic: Working with Share

View Share Entity Details

To view details about an entity, click the Actions icon at the right of the Share entity entry, then click View Details.

For all entities, the details include General, Selected Tables, Publishing details, Recipients, Versions, Log Details, Lineage and Impact sections.

General

The General tab displays the Name and description of the share.

Selected Tables

The Selected Tables tab displays the list of tables you wish to share.

Publishing

This tab displays the publishing details you configure during creation of the share. It displays whether you select live data share or share versioned data.

Recipients

You can review the list of recipients with whom you intend to share objects. It displays the name of the recipient with their mail address.

Versions

If you elect to share versioned data in the publishing section of the share, you will see publishing date, number of objects you share, number of new objects from the previous version of the share and status of the publish.

Log Details

You can view the detailed status of the share in this tab. It provides information such as, the time, Status, Log Level, and Details of each activity that takes place during the running of the job, i.e., creation of the share. It also displays if any errors are encountered during the creation of the share.

Lineage

Lineage displays all known information about the dependencies of the entity, and therefore how the entity was created and how it is linked to other entities.

For example, for a share you create in the database, the lineage is just the cloud location. For a share that you create by adding files from cloud storage, the lineage includes the cloud location of the file you share.

Pointing to the name of an item in the lineage displays the share name, the application that creates it, the type of entity, the path to it, and the schema it is in.

Arrows point from an entity to the entity that it derives from. For example, for a share you create, an arrow points from the cloud location to the share. If you point to an arrow, then a Links Information box appears that shows information about the relationship between the two entities.

To view more details about an item, click the Actions icon for the item, then click Expand. For a cloud location, the files in the location are displayed. Pointing to the name of the file displays the name, application, type, path, and schema of the file. To collapse the display, click the Actions icon, then click Collapse.

Impact

Impact shows all known information about the downstream use of an entity, and therefore how a change in the definition of an entity may affect other entities that depend on it.

For a specific share entity, you can perform the following actions using the Actions context menu:

  • View Details: See View Share Entity Details.
  • Objects: Opens Select Tables dialog of the specific share where you can remove tables from the list of Shared Tables list or add tables from the list of Available Tables list to the list of Shared Tables.
  • Recipients: Opens the Recipients dialog where you can update the list of recipients or delete, copy profile activation link, send an activation mail to the selected recipient.
  • Manage Versions: Opens the Versions dialog which displays the version, publication date, number of objects, number of new objects, status of the publish and Actions related to the publish. You can delete the version or make the selected version as the current version from the Action column. Select Refresh to refresh any updates or select Delete unused versions to delete the selected version. When you delete the unused version, you also receive the option to delete objects in the cloud store location.
  • Publish: Select Publish to publish the updated share.
  • Unpublish: Select Unpublish to unpublish the share.
  • Delete: Removes the Share Provider Entity.

Parent topic: Working with Share

Create Share Recipient

On the Provide Shares page, click the Recipients widget and select + Create Recipient to create a new Share Recipient.

Share Recipients are those with whom we intend to share objects with. You can share objects securely with users outside of Oracle workspace. Apart from creating recipients from the Create Share wizard, you can also create a share recipient from the Create Recipient icon on the Provide Share page and verify the details you configure while its creation.

  1. On clicking the + Create Recipient icon, a Create Share Recipient dialog box appears.Description of create-share-recipient-wizard.png follows
    Description of the illustration create-share-recipient-wizard.png
  2. On the General tab, specify the following fields:
    • Name: Enter the name of the Share Recipient. For example, Marketing_team.

      Note:

      Ensure there are no spaces in the name of the recipient. This field does not support duplicate recipient names. If you try creating a recipient with a duplicate name, the creation of the share fails with the "Name is already used by an existing object" error.
    • Email: Enter the email ID of the recipient. For example, marketing@oracle.com.
    • Description: Add a description. This is optional.

    Click Next to progress to the Shares tab of the Create Share Recipient dialog box.

  3. On the Shares tab, select an available share from the drop-down. As you select the share, it lists under the Granted Shares section. You have the choice to share multiple shares to the recipient.Description of create-share-recipient-shares-tab.png follows
    Description of the illustration create-share-recipient-shares-tab.png

    Select Create to create the Share recipient.

Once you have created the Share recipient, you will be able to view the newly created Share Recipient entity in the display area.

Click the name of the entity or click Action to view details about the share recipient entity. See View Share Recipient Entity Details.

Parent topic: Working with Share

View Share Recipient Entity Details

Click the Actions icon at the right of the Share Recipient entity entry, then click View Details.

For all entities, the details include general details, Log details, Granted Shares, Lineage and Impact.

General

The General tab displays the Name and Email address of the Share Recipient.

Granted Shares

The Granted Shares tab displays the list of shares granted to the recipient.

Log Details

The Log details tab displays the Time, Status, Log Level, Share Name, Request, End Point, Remote address, User Agent and Details of the Recipient.

Lineage

Lineage displays all known information about the dependencies of the entity, and therefore how the entity was created and how it is linked to other entities.

For example, for a share you publish, the lineage includes the files in cloud storage along with the cloud location of the files you share.

To view more details about an item, click the Actions icon for the item, then click Expand. For a cloud location, the files in the location are displayed. Pointing to the name of the file displays the name, application, type, path, and schema of the file. To collapse the display, click the Actions icon, then click Collapse.

Impact

Impact shows all known information about the downstream use of an entity, and therefore how a change in the definition of an entity may affect other entities that depend on it.

Click Actions in the Share Recipient entity card to open the context menu. The actions available are:
  • View Details: See View Share Recipient Entity Details.
  • Granted Share:Opens Manage Granted Shares dialog where you can grant access to a share from list of available shares or you can revoke access from the current selection of share.
  • Send Activation Mail: Opens the mail with the profile link. See About the JSON profile.
  • Copy Profile Activation Link to Clipboard: Copies the JSON profile activation link to clipboard.
  • Rename: Select this option to rename the Recipient.
  • Delete: Select this option to delete the Recipient.

Parent topic: Working with Share

Consume Share

Once the providers share the objects, there are a few steps the recipients need to follow to consume the share.

As a recipient, you will need to download your share profile, subscribe to the data share provider, register the shares and create external tables on top of your shares. The Data Share tool authorizes the access using the JSON profile sent to the recipient using the activation mail. After the access is granted, the Data Share tool links the shared objects with the Data link tool where the consumer can run the data link job and access the objects shared by the provider.

The Consume Share provides an overview on the list of share providers, search for share providers and add a share provider.

To navigate to the Consume Share page, do either of the following:
  • On the Data Studio menu, select Consume Share under the Data Share menu.
  • On the Data Share page, click the Consume Share widget present in the Provider and Consumer section.

The Consume Share page contains:Description of consume-share-page-new.png follows
Description of the illustration consume-share-page-new.png

  1. Search Consumer Share Provider field

    You can search for the Share Recipient you create by entering the name of the Consumer Share Provider. Enter the name of the Consumer Share Provider, for example, REVIEW_PROVIDER and click the magnifer icon to complete the search. The Share tool displays the search results in the display area.

  2. Select + Subscribe to Share Provider to subscribe to a new Share Provider. See Subscribe to Share Provider for exploring this icon.
  3. Toolbar

    The toolbar consists of the sort by, page size, refresh and entity view options.

  4. Delta Share Profile JSON drop area

    You can drop or select the delta share JSON profile from your local system to the drop area here. Selecting the profile opens the Subscribe to Share Provider wizard.

  5. Sort by settings

    When you set sorting values by using the Sort By control in the toolbar, the settings are displayed in small boxes beneath the toolbar. You can delete a setting by clicking the X icon in the box. Or you can change the settings by returning to the Sort By control in the toolbar.

  6. Display area

    The area beneath the Search Consumer Share Providers field displays the entities returned by a search and that match the filter criteria set in the Filters panel. You can sort the entities by clicking the Sort By button and then setting sort values.

Parent topic: Working with Share

About the JSON Profile

In the previous sections we have learned to create share objects, configure the publication and share the activation mail with the profile link to the recipient.

Once the Share tool creates a share object, the recipient receives an activation mail with subject titled Oracle Autonomous Database Data Share.

Description of activation-mail-new.png follows
Description of the illustration activation-mail-new.png

To access the share, you need to register the shared objects using personal authorization JSON profile.

You can click on the profile link to download the JSON profile. Clicking the profile link takes you to a new screen in the browser with a Get Profile Information button as shown below:

Description of json-profile.png follows
Description of the illustration json-profile.png
Select Get Profile Information to download the JSON profile to connect to the share provider.

Note:

You can click on the Get Profile Information button only once. The share tool does not allow you to select Get Profile Information twice. Clicking on it twice brings up a screen which displays the list of causes of the failure to download the profile.
The below profile is an example of the JSON profile you download.
{  "
        shareCredentialsVersion ": 1, 
        "endpoint": "https://myhost.us.example.com/ords/prov/_delta_sharing/", 
        "tokenEndpoint": "http://myhost.us.example.com:1234/ords/pdbdba/oauth/token", 
        "bearerToken": "-xxxxxxxxxxxxxxxxxxxxx", 
        "expirationTime": "2023-01-13T07:53:11.073Z", 
        "clientID": "xxxxxxxxxxxxxxxxxxxxxx..", 
        "clientSecret": "xxxxxxxxxxxxxxxxxxxx.."}
The profile stores the credentials in an encrypted format. The parameters with their description are:
  • shareCredentialsVersion: The version of the share you publish.
  • endpoint: Specifies the share endpoint.
  • tokenEndpoint: Specifies the token endpoint. The Share tool client use the token endpoint to refresh the timeout on your bearer token if you are consuming the share using Oracle.
  • bearerToken: This is a cryptic string which the authentication server generates in response to a login request.
  • expirationTime: This is the time taken for the authentication to expire.
  • ClientID: Specifies the public identifier the authentication server generates when you register the instance for authentication.
  • clientSecret: Specifies a secret identifier the authentication server generates for authorization.
Copy the JSON content of the profile in a notepad. You will need this JSON below to subscribe your share provider.

Note:

Ensure you copy the full JSON content profile, including the left brace and the right brace.

Security enhancements

As a share recipient, you must set up an access control list (ACL) to the share provider’s machine by using the APPEND_HOST_ACE procedure as an ADMIN user, or another privileged user. This allows you to access the share via the Internet.

Note:

This must be done before using the Add Share Provider Wizard to add an access control entry (ACE) to the access control list (ACL) of the host (i.e. Share provider). You can find the host name from the JSON profile you downloaded in the previous step.

For example, if you wish to allow a database user, A_SHARE_USER to access the endpoints on a host (Share provider) named, here is a sample of PL/SQL procedure you will need to run in the SQL worksheet editor as an admin. As a prerequisite, extract the host name from the endpoint property in the delta sharing JSON profile, as provided in the example above. The hostname from the example is myhost.us.example.com. 

BEGIN 
        dbms_network_acl_admin.append_host_ace(    
        host =>'myhost.us.example.com', 
        lower_port=>443,    
        upper_port=>443,
        ace => xs$ace_type(      
        privilege_list => xs$name_list('http', 'http_proxy'),      
        principal_name =>'A_SHARE_USER',
        principal_type => xs_acl.ptype_db)); 
        COMMIT;
        END;        
        /

Following are the parameters with their description:

  • host- Specifies the name or the IP address of the host. The host or domain name is not case-sensitive.
  • lower port- Specifies the lower port of an optional TCP port range.
  • upper port- Specifies the upper port of an optional TCP port range.
  • ace – The Access Control Entry.
  • privilege list- Specifies the list of network privileges to be granted or denied.
  • principal_name- It is the principal (database user or role) to whom the privilege is granted or denied. It is case-sensitive.
  • principal_type- Specifies the type of principal you use.

Refer to the PL/SQL Packages and Types Reference document for more details on the DBMS_NETWORK_ACL_ADMIN package subprograms.

Parent topic: Working with Share

Subscribe to Share Provider

You can subscribe to a share provider and enable access of the objects the provider shares with the recipients.

In this process you will load the provider’s JSON profile for configuration and credentials to enable access to the recipients.

  1. Open the Consume Share page and select + Subscribe to Share Provider. This opens the Subscribe to Share Provider dialog box.
  2. On the Provider Settings pane of the Register Share Provider dialog box, specify the following details:Description of subscribe-share-provider-settings.png follows
    Description of the illustration subscribe-share-provider-settings.png
    • Provider Name: Provider.
    • Description: Add a description. This field is optional.

    Under Share Source section, choose Add New Provider JSON. You can alternatively choose Select from Available Providers if you already have a list of available providers.

    Under Share Provider JSON field, you can share the JSON profile in the following ways:
    • From File: Select this option and click on the drop area titled "Delta Share Profile JSON". Clicking on the area opens your local repository where you can select the JSON profile you had downloaded.
    • JSON: You can select this option and paste the JSON content of the profile you copied into the notepad.

    Click Next to progress to the Add Shares tab.

  3. On the Add Shares tab of the dialog, you will view the list of available shares. Click the share you wish to share with the recipients from the Available Shares and select any of the available options:Description of add-shares.png follows
    Description of the illustration add-shares.png
    • >: This option enables you to move the Available Share to Selected Shares.
    • <: Select this option to remove the selected share from Selected Shares.
    • >>: This option allows you to move all the shares to the Selected Shares screen.
    • <<: Select this option to remove all the selected shares from Selected Shares.

    Click Subscribe to add the share. A confirmation prompt appears when the provider is created successfully. After successful creation of the provider, you will now view the Link Cloud Object screen of the Data Load page.

  4. You can view the name of the Share provider in the cloud storage location field. The share appears in the source file location with the files you add to the share.Description of link-cloud-object.png follows
    Description of the illustration link-cloud-object.png

    Expand the Share folder cart, drag and drop the file you share from the source to the Data Link cart.

    Select Start in the Data link cart to run the data link job.

The objects shared by the provider are now available to the recipient. You can now explore the data available to you in your autonomous database.

Once you have created the Share Provider, you will be able to view the newly created Share Provider entity in the display area.

Click the name of the entity or click Actions to view details about the share recipient entity. See View Share Provider Entity Details .

Parent topic: Working with Share

View Share Provider Entity Details

To view details about the Share Provider entity, click the Actions icon at the right of the Share Provider entity entry, then click View Details.

For all entities, the details include Lineage and Impact sections.

For a specific Share Provider entity, you can perform the following actions using the Actions context menu.

  • View Details: See View Share Provider Entity Details.
  • Manage Shares: Opens a Manage Shares for Share provider dialog box. This lists the shares you select to share with the recipient. You can edit the list of shares you wish to share with the recipient. Click OK to save any changes or select Cancel to discard the process of editing.
  • Rename: Renames the Provider Name. Select Yes to make changes else click No.
  • Delete: Removes the Share Provider Entity.
  • Link Tables: Navigates to the Link Cloud Object page to view and run the related link object.

Parent topic: Working with Share

FAQs on the Data Share Tool

The following are frequently asked questions on the Data Share tool.

  1. When do recipients receive the Data Definition Language (DDL) updates to the source tables?
    The recipients need to link objects again from the cloud storage location.
    • Navigate to the link cloud Object page from the Data Studio menu.
    • Select the table in the Data Link cart.
    • Click on the Actions icon on the table and select Settings.

      This opens the Link Data from Cloud Store Location dialog.

    • Click the Settings pane and select "Drop Table and Create New External Table" option from the drop-down.

    You will receive the updated source table.

  2. When do recipients receive the Data Manipulation Language (DML) updates to the source tables?

    The provider selects the option to publish versioned data, changes will be reflected if the provider publishes a new version.

Parent topic: Working with Share