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, and share your listings.
  • Manage different roles for your Analytics Hub listings, such as listing administrators, subscribers, and viewers.

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 is shared with all Google Cloud users (allauthenticated users). 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.

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 console
  • serviceUsage.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.

Enable the Analytics Hub API

gcloud

Run the gcloud services enable command:

gcloud services enable analyticshub.googleapis.com

Required permissions

To manage listings, you must have one of the following 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.link permission for the datasets for which you want to create listings. The following BigQuery predefined roles contain the bigquery.datasets.link permission:

  • BigQuery Data Owner role (roles/bigquery.dataOwner)
  • BigQuery Admin role (roles/bigquery.admin)

Create a listing

A listing is a reference to a shared dataset that a publisher lists in a data exchange. For more information, see Creating datasets.

To create a listing, follow these steps:

Console

  1. In the Google Cloud console, go to the Analytics Hub page.

    Go to 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 Create listing.

  4. On the Create listing page, in Display name, enter the name of the listing.

  5. 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.

  6. 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.

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

  7. In Source dataset, select the dataset that you want to list in the data exchange. You cannot update this field after the listing is created.

  8. 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.

  9. Click Save.

API

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

POST https://analyticshub.googleapis.com/v1beta1/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. You can either specify US or EU. For more information about locations that support Analytics Hub, see locations.
  • 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 (allauthenticated users). 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

  1. In the Google Cloud console, go to the Analytics Hub page.

    Go to 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 Set permissions.

  5. To add principals, click Add principal.

  6. 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.

  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 more information, see the Analytics Hub Subscriber and Viewer roles.

  8. 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/v1beta1/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.

  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/v1beta1/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.

Update a listing

To update a listing, follow these steps:

Console

  1. In the Google Cloud console, go to the Analytics Hub page.

    Go to Analytics Hub

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

  3. Click the listing that you want to update.

  4. Click Edit listing.

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

  6. To preview changes, click Preview.

  7. To save changes, click Save.

API

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

PATCH https://analyticshub.googleapis.com/v1beta1/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 delete the shared dataset. If you delete a listing, you cannot undo it.

To delete a listing, follow these steps:

Console

  1. In the Google Cloud console, go to the Analytics Hub page.

    Go to Analytics Hub

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

  3. Click the listing that you want to delete.

  4. Click Delete.

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

  6. Click Delete.

API

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

DELETE https://analyticshub.googleapis.com/v1beta1/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