Manage subscriptions

As an Analytics Hub subscriber, you can perform the following tasks:

• Subscribe to a listing.
• List your current subscriptions in a given project.
• Delete a subscription.

As an Analytics Hub publisher, you can perform the following tasks:

• View all subscriptions to your listing.
• Revoke access to a specific subscription.

A subscription is a regionalized resource which resides in the subscriber's project. Subscriptions store relevant information about the subscriber and represents the contract between publisher and subscriber.

Before you begin

To get started with BigQuery sharing (formerly 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
• serviceUsage.services.list
• serviceUsage.services.enable

The following predefined IAM role includes the permissions that you need to enable the Analytics Hub API:

• 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:

gcloud services enable analyticshub.googleapis.com

Required roles

To get the permissions that you need to manage subscriptions, ask your administrator to grant you the Analytics Hub Subscription Owner (roles/analyticshub.subscriptionOwner) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Subscriber workflow

Subscribers can perform the following actions with subscriptions.

Subscribe to listings

To subscribe to listings, follow the steps in Subscribe to listings.

List subscriptions

To view your current subscriptions in a given project, use the projects.locations.subscriptions.list method:

GET https://analyticshub.googleapis.com/v1/projects/PROJECT_ID/location/LOCATION/subscriptions

Replace the following:

• PROJECT_ID: the project ID that contains the subscriptions that you want to list.

• LOCATION: the location for which you want to list the existing subscriptions.

Delete a subscription

To delete a subscription, use the projects.locations.subscriptions.delete method:

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

Replace the following:

• PROJECT_ID: the project ID that contains the subscription that you want to delete.
• LOCATION: the location of the subscription that you want to delete. For more information about locations that support BigQuery sharing, see Supported regions.
• SUBSCRIPTION_ID: the ID of the subscription that you want to delete.

The request body must be empty. If the request is successful, the response body contains an instance of the operation.

When initiated by a subscriber, deleting a subscription deletes the linked dataset from the subscriber's project.

When deleting a subscription from a listing for multiple regions (Preview), all the primary and secondary linked dataset replicas are also deleted from the subscriber's project.

For more information about the tasks that you can perform on subscriptions using the API, see the projects.locations.subscriptions methods.

Publisher workflow

Publishers can perform the following actions with subscriptions. For more information about managing subscriptions to listings, see Manage listings.

List subscriptions

To list all subscriptions, select one of the following options.

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

Revoke a subscription

When a publisher revokes a subscription, the subscriber loses the ability to query the linked dataset. Since this is a publisher-initiated action on a subscriber-owned resource, the linked dataset remains dangling in the subscriber's project. The subscriber can choose to remove the dangling dataset by deleting it.

If a publisher revokes a subscription from a listing for multiple regions (Preview), subscribers are no longer able to query any primary or secondary linked dataset replicas.

To revoke a subscription, select one of the following options:

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

Limitations

Subscriptions are subject to the following limitations:

• Linked datasets created before July 25, 2023 are not backfilled. Only subscriptions created after July 25, 2023 work with the API methods.

What's next

• Read about BigQuery sharing architecture.
• Learn how to view and subscribe to listings.
• Learn about Analytics Hub user roles.
• Learn about creating datasets.
• Learn about BigQuery sharing audit logging.