Syncing custom documentation through an API

Your portal provides a special API for syncing your custom content. To call this API, you must:

  1. Sync your custom content manually at least once.
  2. Create a service account with the proper authorization and key.
  3. Make the HTTP request to sync your content.

This document provides instructions to create a service account and provides examples of making the request via Python or through the command line.

Creating an authorized service account

To use an API to sync your custom content, you need a service account with the proper authorization and key. To create the service account, grant it the proper role and obtain the needed key file, follow these instructions:

Console

  1. Create a service account:

    1. In the console, go to the Service Accounts page.

      Go to Service Accounts

    2. Select the project that your API was configured to use.

    3. Click Create Service Account.

    4. In the Service account name field, enter a name. The console fills in the Service account ID field based on this name.

    5. Optional: In the Service account description field, enter a description for the service account.

    6. Click Create and continue.

    7. Click Done to finish creating the service account.

      Do not close your browser window. You will use it in the next step.

  2. Download a JSON key for the service account you just created:

    1. In the console, click the email address for the service account that you created.
    2. Click Keys.
    3. Click Add key, then click Create new key.
    4. Click Create. A JSON key file is downloaded to your computer.

      Make sure to store the key file securely, because it can be used to authenticate as your service account. You can move and rename this file however you would like.

    5. Click Close.

  3. In the console, go to the Endpoints > Services page for your project.

    Endpoints Services

  4. Click the name of the API for which you need to sync custom content to change its access permissions.

  5. If the Permissions side panel isn't open, click +Permissions.

  6. To grant the created service account access to the API, enter the email address of the created service account in the Add members field.

  7. In the Select a role drop-down list, click Service Management, and select the Service Config Editor role for the service account.

Congratulations! You created the service account, downloaded its private key to a JSON file, and assigned the proper role to the service account.

gcloud

  1. Enter the following command to display the project IDs for your Google Cloud projects:

    gcloud projects list
    
  2. Replace [YOUR_PROJECT_ID] in the following command to set the default project to the one that your API is in:

    gcloud config set project [YOUR_PROJECT_ID]
    
  3. Make sure that the Google Cloud CLI (gcloud) is authorized to access your data and services on Google Cloud:

    gcloud auth login
    

    If you have more than one account, make sure to choose the account that is in the Google Cloud project that the API is in. If you run gcloud auth list, the account that you selected is shown as the active account for the project.

  4. To create a service account, run the following command and replace [SERVICE_ACCOUNT_NAME] and [Service Account to Sync Custom Content] with the name and display name that you want to use:

    gcloud iam service-accounts create [SERVICE_ACCOUNT_NAME] \
      --display-name "[Service Account to Sync Custom Content]"
    

    The command assigns an email address for the service account in the following format:

    [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
    

    This email address is required in the subsequent commands.

  5. Create a service account key file, replace [KEY_FILE] with the filename for your key:

    gcloud iam service-accounts keys create ~/[KEY_FILE] \
      --iam-account [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
    
  6. To grant the service account the access to the API with the custom content, run the following command, replacing [YOUR_SERVICE_NAME] with the name of the API with the custom content:

    gcloud endpoints services add-iam-policy-binding [SERVICE-NAME] \
          --member=serviceAccount:[SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com \
          --role roles/servicemanagement.configEditor
    

Sending a request to sync the custom content

The following examples show how to make a request to sync custom content. The request should be similar to:

 POST https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content/

Replace [YOUR_PROJECT_ID] and [YOUR_SERVICE_NAME] with the appropriate values. When the request completes successfully, the response has an HTTP status code of 200.

The next examples show how to get an access token from Google's authorization servers and use it to make the request to your portal's endpoint by using either Python or the command line:

Python

  1. Install the required Python libraries:
        pip install --upgrade google-auth
  2. To create a Credentials object from the service account's credentials and the scopes the endpoint requires and make the request to sync the content, replace [YOUR_PROJECT_ID], /path/to/service.json and [YOUR_SERVICE_NAME] with the appropriate values in the following script:
    from google.oauth2 import service_account
    from google.auth.transport.requests import AuthorizedSession
    
    SCOPES = ["https://www.googleapis.com/auth/service.management.readonly"]
    SERVICE_ACCOUNT_FILE = "/path/to/service.json"
    PROJECT_ID = "[YOUR_PROJECT_ID]"
    SERVICE_NAME = "[YOUR_SERVICE_NAME]"
    
    credentials = service_account.Credentials.from_service_account_file(
       SERVICE_ACCOUNT_FILE, scopes=SCOPES)
    authed_session = AuthorizedSession(credentials)
    endpoint =
    "https://endpointsportal.%s.cloud.goog/api/v1/%s/custom-content" % (PROJECT_ID, SERVICE_NAME)
    result = authed_session.post(endpoint)
    print result

Command Line

  1. Open Cloud Shell, or open a terminal window if you have the gcloud CLI installed on your Linux computer.
  2. To authenticate to your service account, replace [KEY_FILE] below with the path to your service account key file and run the command:
    gcloud auth activate-service-account --key-file [KEY_FILE]
  3. Get an authorization token using your service account:
    ACCESS_TOKEN=$(gcloud auth print-access-token)
  4. When you call the API, pass the token value as a bearer token in an authorization header. Replace [YOUR_PROJECT_ID] and [YOUR_SERVICE_NAME] with the appropriate values:
    curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content