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 the needed service account and provides examples of making the request via Python or through the command line.

Create 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. Open the Service Accounts page in the GCP Console.

    Go to the Service Accounts page

  2. Click Select a project.

  3. Select your project and click Open. 0. Click add Create Service Account.

  4. In the Service account name field, enter a display name for your service account.

  5. Select the Furnish a new private key checkbox.

  6. For the Key type, use the default type,JSON.
  7. Click Save.

  8. A dialog box shows the key's information. Close the dialog box to continue.

  9. In the GCP Console, go to the Endpoints > Services page for your project.

    Endpoints Services

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

  11. If the Permissions side panel is not open, click +Permissions.

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

  13. In the Select a role drop-down, 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 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 Cloud SDK (gcloud) is authorized to access your data and services on GCP:

    gcloud auth login
    

    If you have more than one account, make sure to choose the account that is in the GCP 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, invoke the following, 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
    

Make 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 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 Cloud SDK 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
Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints Frameworks for App Engine
Need help? Visit our support page.