Manage listings
As an Analytics Hub publisher, you can perform the following tasks:
- Create listings in a data exchange for which you have publishing access.
- Update, delete, share, and view usage metrics for listings.
- Manage different roles for your Analytics Hub listings, such as listing administrators, subscribers, and viewers.
- View all subscribers who subscribed to your listing.
- Monitor usage of your listings.
- Remove subscribers from your listing.
A listing is a reference to a shared dataset that a publisher lists in a data exchange. A listing can be of the following two types based on the Identity and Access Management (IAM) policy that is set for the listing and the type of data exchange that contains the listing:
Public listing. It can be discovered and subscribed by Google Cloud users (
allAuthenticatedUsers
). Listings in a public data exchange are public listings. These listings can be references to a free public dataset or a commercial dataset. If the listing is of a commercial dataset, subscribers can request access to the listing and the data provider contacts those subscribers.Private listing. It is shared directly with individuals or groups. For example, a private listing can reference marketing metrics dataset that you share with other internal teams within your organization. Even though you can allow
allAuthenticatedUsers
to subscribe to your listings, the listing will remain private and won't show as a public listing on the Analytics Hub page. To share such listings with users, share the listing's URL with them. To make a private listing discoverable, you must make your exchange public.
Before you begin
To get started with Analytics Hub, you need to enable the Analytics Hub API inside your Google Cloud project.
Required permissions
To enable the Analytics Hub API, you need the following Identity and Access Management (IAM) permissions:
serviceUsage.services.get/list
to view APIs in Cloud consoleserviceUsage.services.enable
to enable APIs
Each of the following predefined IAM roles includes the permissions that you need to enable the Analytics Hub API:
roles/editor
roles/owner
roles/serviceusage.serviceUsageAdmin
For more information about IAM roles in BigQuery, see Predefined roles and permissions.
Enable the Analytics Hub API
To enable the Analytics Hub API, do the following:
Console
Go to the Analytics Hub API for your Google Cloud project and enable it.
gcloud
Run the gcloud services enable command:
gcloud services enable analyticshub.googleapis.com
Required permissions
To manage listings and subscriptions, you must have one of the following Analytics Hub roles:
Analytics Hub Publisher role (
roles/analyticshub.publisher
), which lets you create, update, delete, and set IAM policies on your listings.Analytics Hub Listing Admin role (
roles/analyticshub.listingAdmin
), which lets you update, delete, and set IAM policies on your listings.Analytics Hub Admin role (
roles/analyticshub.Admin
), which lets you create, update, delete, and set IAM policies on all listings in your data exchange.
For more information, see Analytics Hub user roles. To learn how to grant these roles to other users, see Create a listing administrator.
Additionally, to create listings, you must also have the
bigquery.datasets.update
permission for the datasets for which you want to
create listings. The following BigQuery predefined
roles contain the
bigquery.datasets.update
permission:
- BigQuery Data Owner role (
roles/bigquery.dataOwner
) - BigQuery Admin role (
roles/bigquery.admin
)
To view all data exchanges across projects in an organization that you
have access to, you must have the resourcemanager.organizations.get
permission. The following BigQuery predefined
role contains this permission:
roles/browser
View data exchanges
To view the list of data exchanges in your organization that you have access to, see View data exchanges. If the data exchange is in another organization, then the Analytics Hub administrator must share a link to that data exchange with you.
Create a listing
A listing is a reference to a shared dataset that a publisher lists in a data exchange.
You shouldn't create a listing for a dataset that uses a customer-managed encryption key because subscribers won't have access to the Cloud KMS key required to access the dataset. Instead, we recommend copying datasets that use customer-managed encryption keys into datasets that are created using a Google-managed encryption key and then create a listing from the copied dataset. Another option is to create materialized views in a dataset using a Google-managed encryption key that references tables using customer-managed encryption keys.
To create a listing, follow these steps:
Console
Go to the Analytics Hub page.
A page appears that lists all data exchanges that you can access.
Click the data exchange name in which you want to create the listing.
Click
Create listing.On the Create listing page, in Display name, enter the name of the listing.
If you are creating a commercial dataset, then you must fill in the Request access contact field. You must enter an email or URL of the intake form for subscribers to contact you.
Optional: Enter the following details:
Primary contact: enter an email or a URL of the primary contact for the listing.
Category: select up to two categories that best represent your listing. Subscribers can filter listings based on these categories.
Provider: expand the Provider section and specify details in the following fields:
- Provider name: the name of the dataset provider.
- Provider primary contact: an email or a URL of the dataset provider's primary contact.
Subscribers can filter listings based on the data providers.
Publisher: expand the Publisher section and specify details in the following fields:
- Publisher name: the name of the publisher who's creating the listing.
- Publisher primary contact: an email or a URL of the dataset publisher's primary contact.
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.
In Source dataset, select the dataset that you want to list in the data exchange. The source dataset must be in the same region as the data exchange. You cannot update this field after the listing is created.
In Data Egress (preview), select the appropriate data egress option. Only subscribers with non-edition offerings or Enterprise Plus edition can query data with data egress restrictions.
- To apply data egress restrictions on your shared dataset, but not on your 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 data as well.
Optional: In the Documentation > Markdown section, you can enter additional information such as sample queries that you can run on the dataset, links to any relevant documentation, and any additional information that can help subscribers to use your dataset.
Click Save.
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 Analytics Hub, see Supported regions.DATAEXCHANGE_ID
: the data exchange ID.LISTING_ID
: the listing ID.
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.
Give users access to a listing
If you want to give users access to a private listing, you must set
IAM policy for an individual or a group for that listing. For a
commercial listing, your data exchange must be public.
Listings in a public data exchange appears in Analytics Hub for
all Google Cloud users (allAuthenticatedUsers
).
To enable users to request access for commercial listings, you must grant users
the Analytics Hub Viewer role.
To give users access to view or subscribe to your listing, follow these steps:
Console
Go to the Analytics Hub page.
Click the data exchange name that contains the listing.
Click the listing for which you want to add subscribers.
Click
Set permissions.To add principals, click
Add principal.In the New principals field, add the following details based on the type of listing:
For a private listing, enter emails of the identity to whom you want to grant access.
For a public listing, add
allAuthenticatedUsers
.
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, select the Analytics Hub Viewer role. This role lets users view the listing and request access.
For a private or non-commercial public listing, select the Analytics Hub Subscriber role. This role lets users subscribe to your listing.
For more information, see the Analytics Hub Subscriber and Viewer roles.
Click Save.
API
Read the existing policy with the listing
getIamPolicy
method by using theprojects.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.
Analytics Hub returns the current policy in the response.
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 togroup:subscribers@example.com
, add the following binding to the policy:{ "members": [ "group:subscribers@example.com" ], "role":"roles/analyticshub.subscriber" }
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.
Create a listing administrator
To let users manage listings, you must create Analytics Hub listing administrators. To create listing administrators, you need to grant users the Analytics Hub Publisher or the Analytics Hub Listing Admin role at the listing level. For more information about how to grant these roles for a listing, see Grant the role for a listing.
View all subscriptions
To view all current subscriptions to your listing, select one of the following options:
Console
Go to the Analytics Hub page.
Click the data exchange name that contains the listing for which you want to manage the subscriptions.
Click the listing for which you want to list all subscribers.
To view all subscribers of your listing, click Manage subscriptions.
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:
Go to the BigQuery page.
In the Explorer pane, expand your project and select the shared dataset.
In the
Sharing list, select Manage subscriptions.
SQL
The following example uses the
INFORMATION_SCHEMA.SCHEMATA_LINKS
view
to list all linked datasets 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 | +----------------+-------------+----------------------------+------------------------------+--------------------+--------------------------------+
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.
Remove a subscription
When you remove a subscription created before July 25, 2023 from your listings, the linked dataset gets unlinked from the shared dataset. Subscribers can still see the datasets in their projects but they are no longer linked with the shared dataset.
To remove a subscription created before July 25, 2023 from your listings, follow these steps:
To list all subscribers of a listing, follow the Google Cloud console instructions in View all subscriptions.
To remove a subscriber from a listing, click
Delete. If you want to remove all subscriptions, click Remove all subscriptions.In the Remove subscription? dialog, enter
remove
to confirm.Click Remove.
To remove subscriptions created after July 25, 2023, follow these steps:
Console
To list all subscribers of a listing, follow the Google Cloud console instructions in View all subscriptions.
Click the Subscriptions tab.
To remove a subscriber from a listing, select the Subscription(s) you would like to remove and click
Remove Subscriptions.In the Remove subscription? dialog, enter
remove
to confirm.Click Remove.
API
Use the projects.locations.subscriptions.revoke method (preview).
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.
Update a listing
To update a listing, follow these steps:
Console
Go to the Analytics Hub page.
Click the data exchange name that contains the listing.
Click the listing that you want to update.
Click
Edit listing.Modify values in the fields. You can modify all values except the source dataset of the listing.
To preview changes, click Preview.
To save changes, click Save.
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.
For more information about the tasks that you can perform on listings using
APIs, see projects.locations.dataExchanges.listings
methods.
Delete a listing
When you delete a listing, subscribers cannot view that listing. However, deleting a listing does not delete the linked dataset from your subscribers' projects. If you want to remove all access to your data, you must select one of the following options:
- Delete the shared dataset
- Delete all linked datasets to your shared dataset
If you delete a listing, you cannot undo it. To delete a listing, follow these steps:
Console
Go to the Analytics Hub page.
Click the data exchange name that contains the listing.
Click the listing that you want to delete.
Click
Delete.In the Delete exchange? dialog, confirm deletion by typing delete.
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.
What's next
- Read about Analytics Hub architecture
- Learn how to view and subscribe to listings.
- Learn about Analytics Hub user roles.
- Learn about creating datasets.
- Learn about Analytics Hub audit logging.
- Learn how to monitor listings.