Manage listings

Console

Go to the Analytics Hub APIpage and enable the Analytics Hub API for your Google Cloud project.

Enable the Analytics Hub API

gcloud

Run the gcloud services enable command:

gcloud services enable analyticshub.googleapis.com

Console

1. Go to the Sharing (Analytics Hub)page.

   Go to Sharing (Analytics Hub)

   A page appears that lists all data exchanges that you can access.

2. Click the data exchange name in which you want to create the listing.

3. Click add_box Create listing.

4. In the Configure datasection, in the Resource typemenu, select BigQuery datasetor Pub/Sub Topic.

   • If you select BigQuery dataset, then do the following:

     1. In the Shared datasetmenu, select an existing dataset, or click Create a datasetto create a new dataset. Select the dataset that you want to list in the data exchange. The dataset must be in the same region as the data exchange. You cannot update this field after the listing is created. The source dataset name and the ID of the project that contains the dataset are returned when subscribers view the metadata of their linked dataset .

     2. Expand the Region data availabilitymenu ( Preview ) to make the shared dataset available in additional regions. The menu displays the regions where dataset replicas exist with the Ready to uselabel. Before configuring the listing for multiple regions, verify you've enabled cross-region dataset replication on the shared dataset, as you can select only regions where cross-region dataset replication is enabled. All other regions are labeled as Unavailable. If no additional region is selected, the listing uses the shared dataset primary region by default, which is labeled as Provider primary.

     3. In Data Egress controls, select the appropriate data egress option.

        • To apply data egress restrictions on your shared dataset, but not on query results of your shared dataset, select Disable copy and export of shared data.
        • To apply data egress restrictions on your shared dataset and query results of your shared dataset, select Disable copy and export of query results, which will automatically set Disable copy and export of shared dataas well.
        • To apply data API copy and export egress restrictions on your shared dataset, select Disable copy and export of tables through APIs, which will automatically set Disable copy and export of shared dataas well.

   • If you select Pub/Sub Topic, then in the Shared topicmenu, you can select an existing Pub/Sub topic, or click Create a topicto create a new topic.

5. In the Listing detailssection, in Display name, enter the name of the listing.

6. Enter the following optional details:

   • Category: select up to two categories that best represent your listing. Subscribers can filter listings based on these categories.

   • Data affinity: regions used by the publisher for publishing the data if you're using a Pub/Sub topic. This information is useful for subscribers to minimize or avoid Pub/Sub network egress costs by reading the data from the same region. For more information about egress costs, see Data transfer costs .

   • Icon: an icon for your listing. PNG and JPEG file formats are supported. Icons must have a file size of less than 512 KiB and dimensions of no more than 512 x 512 pixels.

   • Description: a brief description about your listing. Subscribers can search for listings based on the description.

   • Public Discoverability: enable public discoverability of your listing in the BigQuery sharing catalog. If you enable this option, grant allUsers or allAuthenticatedUsers the Analytics Hub Viewer role ( roles/analyticshub.viewer ). For more information, see Grant the role for a listing . If the exchange is already public , listing permissions are already inherited and no further action is required.

     Publicly discoverable exchanges can't have private listings due to permission inheritance, but private exchanges can have public listings. For public listings to be created, the project the data listing is in must have an associated organization and billing account. If you're creating a Cloud Marketplace-integrated commercial listing , we recommend making your listing publicly discoverable.

   • Documentation > Markdown: additional information such as links to any relevant documentation and any additional information that can help subscribers to use your topic.

7. On the Listing contact informationsection, enter the following optional details:

   • Primary contact: enter an email ID or a URL of the primary contact for the listing.

   • Request access contact: enter an email ID or URL of the intake form for subscribers to contact you.

   • Provider: expand the Providersection and specify details in the following fields:

     • Provider name: the name of the topic provider.
     • Provider primary contact: an email ID or a URL of the topic provider's primary contact.

     Subscribers can filter listings based on the data providers.

   • Publisher: expand the Publishersection and specify details in the following fields:

     • Publisher name: the name of the publisher who's creating the listing.
     • Publisher primary contact: an email ID or a URL of the topic publisher's primary contact.

8. Review the Listing previewsection.

9. Click Publish.

API

Use the projects.locations.dataExchanges.listings.create method .

POST https://analyticshub.googleapis.com/v1/projects/ PROJECT_ID 
/location/ LOCATION 
/dataExchanges/ DATAEXCHANGE_ID 
/listings?listingId= LISTING_ID 

Replace the following:

• PROJECT_ID : the project ID that contains the data exchange in which you want to create the listing.
• LOCATION : the location for your data exchange. For more information about locations that support BigQuery sharing, see Supported regions .
• DATAEXCHANGE_ID : the data exchange ID.
• LISTING_ID : the listing ID.

In the body of the request, provide the listing details .

To create a listing for multiple regions ( Preview ), specify the additional regions in the bigqueryDataset.replicaLocations field in the request body. Before configuring the listing for multiple regions, verify you've enabled cross-region dataset replication on the shared dataset. You can select only regions where cross-region dataset replication is enabled. If this optional field is not included, the listing is created using the shared dataset's primary region.

If the request is successful, the response body contains details of the listing. If you enable subscriber email logging ( Preview ), the listing response contains log_linked_dataset_query_user_email: true .

For more information about the tasks that you can perform on listings using APIs, see projects.locations.dataExchanges.listings methods .

Console

1. Go to the Sharing (Analytics Hub)page.

   Go to Sharing (Analytics Hub)

2. Click the data exchange name that contains the listing.

3. Click the listing for which you want to add subscribers.

4. Click person Set permissions.

5. To add principals, click person_add Add principal.

6. In the New principalsfield, add the following details based on the type of listing:

   • For a private listing, enter email IDs of the identity to whom you want to grant access.

   • For a public listing, add allAuthenticatedUsers .

   • For a public listing discoverable to everyone, including non-Google Cloud users, add allUsers .

7. For Select a role, hold the pointer over Analytics Hub, and then based on the type of listing, select one of the following roles:

   • For a commercial listing (including Cloud Marketplace-integrated listings), select the Analytics Hub Viewerrole. This role lets users view the listing and request access .

   • For a private or non-commercial public listing, select the Analytics Hub Subscriberrole. This role lets users subscribe to your listing .

   • For Cloud Marketplace-integrated listings, the Analytics Hub Subscriber role doesn't need to be granted, as subscriptions are automatically governed and managed based on the Cloud Marketplace order.

   For more information, see the Analytics Hub Subscriber and Viewer roles .

8. Click Save.

   For more information, see the Analytics Hub Subscriber and Viewer roles .

9. Click Save.

API

1. Read the existing policy with the listing getIamPolicy method by using the projects.locations.dataExchanges.listings.getIamPolicy method .

   POST https://analyticshub.googleapis.com/v1/projects/ PROJECT_ID 
   /locations/ LOCATION 
   /dataExchanges/ DATAEXCHANGE_ID 
   /listings/ LISTING_ID 
   :getIamPolicy

   Replace the following:

   • PROJECT_ID : the project ID—for example, my-project-1 .
   • LOCATION : the location of the data exchange that contains the listing.
   • DATAEXCHANGE_ID : the data exchange ID.
   • LISTING_ID : the listing ID.

   Sharing returns the current policy in the response.

2. To add or remove members and their associated roles, edit the policy with a text editor. Use the following format to add members:

   • user:test-user@gmail.com
   • group:admins@example.com
   • serviceAccount:test123@example.domain.com
   • domain:example.domain.com

   For example, to grant the roles/analyticshub.subscriber role to group:subscribers@example.com , add the following binding to the policy:

   {
    "members": [
      "group:subscribers@example.com"
    ],
    "role":"roles/analyticshub.subscriber"
   }

3. Write the updated policy by using the projects.locations.dataExchanges.listings.setIamPolicy method . In the body of the request, provide the updated IAM policy from the previous step.

   POST https://analyticshub.googleapis.com/v1/projects/ PROJECT_ID 
   /location/ LOCATION 
   /dataExchanges/ DATAEXCHANGE_ID 
   /listings/ LISTING_ID 
   :setIamPolicy

   In the body of the request, provide the listing details. If the request is successful, then the response body contains details of the listing.

For more information about the tasks that you can perform on listings using APIs, see projects.locations.dataExchanges.listings methods .

Console

1. Go to the Sharing (Analytics Hub)page.

   Go to Sharing (Analytics Hub)

2. Click the data exchange name that contains the listing for which you want to manage the subscriptions.

3. Click the listing for which you want to list all subscribers.

4. To view all subscribers of your listing, click Manage subscriptions.

   

5. Optional: You can filter results by subscriber details.

Alternatively, if you have access to the shared dataset , you can follow these steps to list subscribers:

1. Go to the BigQuerypage.

   Go to BigQuery

2. In the Explorerpane, expand your project and select the shared dataset.

3. In the person_add Sharinglist, select Manage subscriptions.

SQL

The following example uses the INFORMATION_SCHEMA.SCHEMATA_LINKS view to list all the linked datasets linked to a shared dataset in myproject that are in the us region:

SELECT * FROM `myproject`.`region-us`.INFORMATION_SCHEMA.SCHEMATA_LINKS;

The output is similar to the following. Some columns are omitted to simplify the output.

+----------------+-------------+----------------------------+------------------------------+--------------------+--------------------------------+
|  catalog_name  | schema_name | linked_schema_catalog_name | linked_schema_catalog_number | linked_schema_name | linked_schema_org_display_name |
+----------------+-------------+----------------------------+------------------------------+--------------------+--------------------------------+
| myproject      | myschema1   | subscriptionproject1       |                 974999999291 | subscriptionld1    | subscriptionorg                |
| myproject      | myschema2   | subscriptionproject2       |                 974999999292 | subscriptionld2    | subscriptionorg                |
| myproject      | myschema3   | subscriptionproject3       |                 974999999293 | subscriptionld3    | subscriptionorg                |
+----------------+-------------+----------------------------+------------------------------+--------------------+--------------------------------+

For a listing with multiple regions ( Preview ), you can view the subscriptions across different regions by replacing the us region with the intended replica location. For example, to view the linked datasets linked to a shared dataset in myproject that are in the eu region, use the following query:

SELECT * FROM `myproject`.`region-eu`.INFORMATION_SCHEMA.SCHEMATA_LINKS;

API

Use the projects.locations.dataExchanges.listings.listSubscriptions method .

GET https://analyticshub.googleapis.com/v1/projects/ PROJECT_ID 
/location/ LOCATION 
/dataExchanges/ DATAEXCHANGE_ID 
/listings/ LISTING_ID 
:listSubscriptions

Replace the following:

• PROJECT_ID : the project ID of the listing that you want to subscribe to.
• LOCATION : the location for the listing that you want to subscribe to.
• DATAEXCHANGE_ID : the data exchange ID that contains the listing that you want to subscribe to.
• LISTING_ID : the ID of the listing that you want to subscribe to.

Console

1. To list all subscribers of a listing, follow the Google Cloud console instructions in View all subscriptions .

2. Click the Subscriptionstab.

3. To remove a subscriber from a listing, select the Subscription(s) you would like to remove and click delete Remove Subscriptions.

4. In the Remove subscription?dialog, enter remove to confirm.

5. Click Remove.

API

Use the projects.locations.subscriptions.revoke method .

POST https://analyticshub.googleapis.com/v1/projects/ PROJECT_ID 
/location/ LOCATION 
/subscriptions/ SUBSCRIPTION_ID 
:revoke

Replace the following:

• PROJECT_ID : the project ID of the subscription that you want to remove.
• LOCATION : the location of the subscription that you want to remove.
• SUBSCRIPTION : the ID of the subscription that you want to remove.

Console

1. Go to the Sharing (Analytics Hub)page.

   Go to Sharing (Analytics Hub)

2. Click the data exchange name that contains the listing.

3. Click the listing that you want to update.

4. Click mode_edit Edit listing.

5. Modify values in the fields. You can modify all values except the source dataset of the listing.

6. Optional:

   • If you enable public discoverability, grant allUsers or allAuthenticatedUsers the Analytics Hub Viewer role ( roles/analyticshub.viewer ). For more information, see Grant the role for a listing
   • If you disable public discoverability, remove the Analytics Hub Viewer role from allUsers and allAuthenticatedUsers . Public exchanges can't have private listings, but private exchanges can have public listings.
   • If you enable and save subscriber email logging, this setting cannot be edited. To disable email logging, delete the listing and recreate it without clicking the Subscriber email loggingtoggle ( Preview ).
   • Add or remove regions from the listing ( Preview ). Before adding multiple regions, verify you've enabled cross-region dataset replication on the shared dataset. When removing regions, delete the shared dataset replica in that region first.

7. Preview the listing.

8. To save changes, click Save. To avoid discrepancies with Cloud Marketplace-integrated listings, a notification appears that prompts an update to the Cloud Marketplace data product listing.

API

Use the projects.locations.dataExchanges.listings.patch method .

PATCH https://analyticshub.googleapis.com/v1/projects/ PROJECT_ID 
/location/ LOCATION 
/dataExchanges/ DATAEXCHANGE_ID 
/listings/ LISTING_ID 
?updateMask= UPDATEMASK 

Replace UPDATEMASK with the list of fields that you want to update. For updating multiple values, use a comma-separated list. In the body of the request, specify the updated values.

In the body of the request, specify the updated values for the following fields:

• Display name
• Description
• Categories
• Documentation
• Icon
• Primary contact
• Public discoverability
• Subscriber email logging ( Preview )

For details on these fields, see Resource: Listing .

When updating the replica regions for your listing, ensure that you specify all applicable regions. Before updating the listing, verify you've enabled cross-region dataset replication on the shared dataset. You can add only regions ( Preview ) where the shared dataset is replicated. To remove a region, delete the shared dataset replica for the region before removing it from the listing. You can update replica regions only for newly created listings for multiple regions. You can't convert pre-existing listings to listings for multiple regions.

For more information about the tasks that you can perform on listings using APIs, see projects.locations.dataExchanges.listings methods .

Console

1. Go to the Sharing (Analytics Hub)page.

   Go to Sharing (Analytics Hub)

2. Click the data exchange name that contains the listing.

3. Click the listing that you want to delete.

4. Click delete Delete.

5. In the Delete listing?dialog, confirm deletion by typing delete.

6. Click Delete.

API

Use the projects.locations.dataExchanges.listings.delete method .

DELETE https://analyticshub.googleapis.com/v1/projects/ PROJECT_ID 
/location/ LOCATION 
/dataExchanges/ DATAEXCHANGE_ID 
/listings/ LISTING_ID 

For more information about the tasks that you can perform on listings using APIs, see projects.locations.dataExchanges.listings methods .