Integrating your support

This section describes the support workflow when you intend to provide support as a part of your solution.

Your system needs to be integrated with Google's so that you can provide support to your customers who have purchased your solutions through Google. The integration is based on Google providing you with the following:

  • A key that you will use to verify a user's support eligibility as part of the sign-up process.

  • An API (the subscriptions API) to which you can pass the key to periodically poll the status of a user's support eligibility.

Obtaining the user's support ID

The support integration focuses around an external account ID, which your users see as their support ID.

Users give you their support ID in one or more of the following ways:

  • You create a support workflow and provide a URL to the start of the workflow. Then, Google sends you the external account ID in the URL.
  • When you create your solution in the Partner Portal, you can select the option to display a button that users can click to see their support ID. They can then copy and send you the support ID via email, input it into a web form, or read it to a support representative over the phone.

If you implement the support workflow, it must accept the external account ID as part of the URL. The external account ID can be part of the URL path, or as a query parameter value, as in the examples below:

# External account ID in path
http://example.com/mysupportpage/{external_account_id}?someparameter=yes

# External account ID as a query parameter
http://example.com/mysupportpage?eid={external_account_id}&something_else

The text {external_account_id} in the URL gets replaced with the external account ID. If you have multiple solutions listed in GCP Marketplace, you might want to include a query parameter to identify the solution that the URL is for.

Using the subscriptions API

After you have the user's external account ID, you can use the Google-provided subscriptions API to verify the support eligibility for their account at any time. Eligibility is tracked by checking for entities called subscriptions.

Each subscription has a unique subscription ID number, and a unique subscription is created per customer for every solution that you list in GCP Marketplace, so you can also query a subscription by subscription ID to get additional details about a customer's history with your solution, such as their start date, end date, and so on.

Accessing the subscriptions API

The subscriptions API is a non-public API, so developers and projects needing access must be whitelisted.

To get whitelisted and setup, follow these steps:

  1. Send a list of email addresses for developers who need to access the API documentation to your GCP Marketplace Partner Engineer, or to cloud-partners@google.com. These must be the exact email addresses the developers will use to log in to http://console.developers.google.com. These developers will be added to the group that grants permission to access the subscription API's documentation.

  2. Send your solution's project ID to your GCP Marketplace Partner Engineer and request that it be granted permission to call the API. Multiple projects can be whitelisted if needed.

  3. Enable the cloud billing API by expanding the menu near the upper left side of https://console.developers.google.com, clicking APIs & Services, and then searching for and enabling the Cloud Billing API.

  4. Create an OAuth2 service account associated with your project, and send the email address for this account to your GCP Marketplace Partner Engineer. This user will be whitelisted to read all subscriptions for you, and will be used to authorize all requests except for those made by requesting the customer's permission using an OAuth dialog.

Because the subscriptions API is not a public API, it is not included in the Python client library by default. If you plan to use the Python client library with this API, you must also contact your Google Partner Engineer for help with accessing the discovery file.

In the example initialization below, the discovery filename is set to the path the discovery file downloaded to.

   # Load the local copy of the discovery document
   f = file(os.path.join(os.path.dirname(__file__),
         "cloudbilling-subscriptions_discovery.json"), "r")
   discovery = f.read()
   f.close()

   # Construct a service from the local documents
   service = build_from_document(discovery,
         base="https://www.googleapis.com/",
         http=http)

The client library also supports OAuth authentication, both for customer credentials and OAuth2 service accounts. For more information, see the OAuth 2.0 documentation in the Google API Client Library for Python.

Querying the subscriptions API

To get permission to access subscriptions data, you need to create an OAuth2 service account and tell us the account you intend to use to authorize API requests. Google will then grant that service account access to read your subscriptions for all customers. For more information, see Using OAuth 2.0 for Server to Server Applications.

The API is a read-only RESTful API that returns subscription resources, which can be used to get the following info:

  • name—An identifier for a single subscription resource.
  • externalAccountId—An identifier for a single billing account.
  • version—A version number that updates every time the record is modified. This can be used to easily detect any changes since the last read.
  • status—One of the following values:
    • ACTIVE—The subscription is currently active and the customer should be able to receive support from you. A subscription is considered active if the account has had an active VM in the last 30 days.
    • COMPLETE—The subscription is no longer active, because the customer does not have any active VMs running with your solution, and has not for the last 30 days.

  • subscribedResources—A list of resources covered by this subscription.
  • startDate—The date the subscription began, formatted as a string in RFC 3339 format.
  • endDate—The date the subscription has ended (if it has ended), formatted as a string in RFC 3339 format.
  • Label for last heartbeat timestamp (with key)—The value of this label indicates the timestamp of the last heartbeat of any virtual machine running the solution. For example: cloudmarketplacepartner.googleapis.com/last_heartbeat_us

When a customer clicks the link to access your site from the Google Cloud Platform Console, you need to verify that the customer is authorized to use the link by making the following requests:

  1. List the subscriptions for the external account ID
  2. Find the active subscription for the solution
  3. Get the subscription information using the subscription ID

If the customer is an authorized user, the request will succeed. If the customer is not an authorized user for the subscription, the call will return an unauthorized error code (HTTP 403).

This requires you to request the customer's permission to read their subscriptions data during the signup process, using a standard OAuth request flow.

Later requests to refresh subscription data use your previously-created service account.

Customer support registration flow

After a customer has deployed your solution through GCP Marketplace or through Compute Engine APIs, the Google Cloud Platform Console shows them a link to your site to complete registration for support. The link will include the external account ID to be used for that account.

Your site should allow the customer to create an account and supply any contact information they need; Google will not provide any personally identifiable information about the customer to you. You are responsible for maintaining a mapping between their account and the Google-supplied external account ID.

Was this page helpful? Let us know how we did:

Send feedback about...

GCP Marketplace