Google Cloud Platform Marketplace Support Integration

This page describes the support workflow when you intend to provide support free, included with your solution price.

In this case, your system needs to be integrated with Google's so that you can provide support to your customers who have purchased it 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.

High Level Design

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 in email, add to a web form, or read 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.

After you have the user's external account ID, Google provides an API that you use to query support eligibility for that account. When a user arrives at their signup flow, you can use this API to verify that the user is eligible for support. You can also use the API at any time to check whether the user is still eligible for support.

Signup Flow

After a customer has deployed your solution through GCP Marketplace or through Google 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.

Subscriptions API

A subscription is an entity that you can query to check support eligibility. To do this, you'll use the subscriptions API. Every subscription is identified by a unique subscription ID key. The API provides the ability to list all your subscriptions belonging to a particular external account ID.

Note that there is one subscription created for every solution you've listed in GCP Marketplace. So, you can also query a subscription by subscription ID to get more details such as status, start date, end date, and so on.

The API is a read-only RESTful API that will return subscription resources. The fields in a subscription resource are:

  • ID—An identifier for a single subscription resource.
  • External account ID—An identifier for a single billing account.
  • Version—A version number updated every time the record is modified. Optionally, you can use this for easily detecting 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 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.
  • Subscribed Resources—A list of resources covered by this subscription.
  • Start Date—The date the subscription began, formatted as a string in RFC 3339 format.
  • End Date—If the subscription has ended, the date it ended, formatted as a string in RFC 3339 format. If the subscription is in ACTIVE or PENDING status this field will be omitted.
  • Label for last heartbeat timestamp (with key)—The value of this label indicates the timestamp of the last heartbeat of a virtual machine with the solution. For example:
    cloudmarketplacepartner.googleapis.com/last_heartbeat_us

API Authorization

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.

When the 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. Make the following requests to read the subscription as normal, and use the customer’s permission:

  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 service account as described above under API Authorization.

Detailed Integration steps

Get access to the Subscriptions API

The Subscription API is a non-public API, so developers and projects which need 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 cloud-partners@google.com. These must be the email addresses those developers use to login to http://console.developers.google.com. These developers will be added to the group that grants permission to access the documentation site for the subscription API.

  2. Create a project at https://console.developers.google.com/project and send the project ID to your GCP Marketplace Partner Engineer. This project will be given permission to call the API. Multiple projects can be whitelisted if needed. We recommend that you create a separate project from your public VM images for developer accounts.

  3. To enable the cloud billing API for your projects, expand the menu near the upper left side of the https://console.developers.google.com, and click APIs & Services, then search for and enable the Cloud Billing API.

  4. Create an OAuth2 service account associated with the project created in step 2 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 (see the previous section on Signup/Link Verification).

Accessing the API

Using the Client Library

Because the subscriptions API is not a public API, it is not included in the Python client library by default. To use the library with this API, you must contact your Google Partner Engineer as described in the whitelisting section above for help 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.

OAuth Scopes

https://www.googleapis.com/auth/cloud-billing-partner-subscriptions.readonly

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

Send feedback about...

GCP Marketplace