Getting Started with the Admin API

This guide is designed to help you learn how to use the Google App Engine Admin API to deploy a sample Python application to App Engine. You can use the overall process to gain insight into how you can create code that programmatically manages and deploys your apps.

In this guide, the sample used is a simple Hello World app that displays the text "Hello, World!" and is available in GitHub. For authorization with the Cloud Platform Console, an OAuth client ID and a web browser is used. To demonstrate the individual steps of the process, cURL commands are provided so that you can send HTTP requests from your terminal.

Objectives

  • Enable the APIs in your Cloud Platform Console project and create OAuth client ID credentials.
  • Obtain access tokens for authenticating with App Engine.
  • Use the Admin API to deploy the sample app to App Engine.
  • Optional: Configure traffic to the version where you deployed the sample app.

Before you begin

Tip: If you want to manually run the Hello World app locally, see Quickstart for Python App Engine Standard Environment.

Configuring your Cloud Platform project

Enable the Google App Engine Admin API and the Google Cloud Storage APIs in your Cloud Platform project and configure credentials:

Enable the APIs

  1. In the wizard, select an existing project from the list or click Continue to create a new project.
  2. Click Continue to create an OAuth client ID credential:

    1. In the OAuth consent screen specify at least your Email address and the Product name shown to users.
    2. Save the consent screen settings and then switch to the Credentials tab by clicking Save.
    3. Click Create credentials and then OAuth client ID to create a client ID.
    4. Click Web application, specify a name, and then use https://www.google.com as the redirect URI.

    5. Click Create to save the credential.

    6. Take note of the client ID that is displayed because it will be used in a later step for requesting your access token.

For more information about creating credentials for the Admin API,see Accessing the API.

Creating a configuration file

Create a configuration file that defines the Hello World app deployment. In a file named app.json, you define the Google Cloud Storage bucket of the Hello World app in the sourceURL field and the configuration information for the version, including the version ID in the id field.

{
  "deployment": {
    "files": {
      "main.py": {
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      },
    }
  },
  "handlers": [
    {
      "script": {
        "scriptPath": "main.app"
      },
      "urlRegex": "/.*"
    }
  ],
  "runtime": "python27",
  "threadsafe": true,
  "id": "appengine-helloworld",
  "inboundServices": [
    "INBOUND_SERVICE_WARMUP"
  ]
}

For example, root/python-docs-samples/appengine/standard/hello_world/app.json

Authorizing HTTP requests

Authenticate with App Engine so that you can send HTTP requests with the Admin API. In this step we use the OAuth client ID credential and a web browser to obtain access tokens. For more information about authentication flows, see Accessing the API.

  1. In your web browser, request an access token by using the client ID of your API credentials. The following example uses client_id=[MY_CLIENT_ID] and redirect_uri=https://www.google.com, where [MY_CLIENT_ID] is the client ID of the credential that you created earlier:

    https://accounts.google.com/o/oauth2/v2/auth?response_type=token&client_id=[MY_CLIENT_ID]&scope=https://www.googleapis.com/auth/cloud-platform&redirect_uri=https://www.google.com&prompt=consent
    
  2. Retrieve the access token from the request response.

    The address field in your web browser should contain the redirect URI that you specified in your credentials along with the access token appended to the URI, for example:

    https://www.google.com/#access_token=[MY_ACCESS_TOKEN]&token_type=Bearer&expires_in=3600
    

    Now you can use the access token [MY_ACCESS_TOKEN] that is provided in the access_token field to send HTTP requests to your Cloud Platform project.

    Remember: Your access token expires approximately 60 minutes after it is issued and must be refreshed thereafter.

Deploying the Hello World app

You use an HTTP request to deploy the Hello World app with the Admin API:

  1. Send an HTTP POST request using the Admin API to deploy a version of the Hello World app to your App Engine application, for example:

    POST https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions app.json
    

    Example cURL command:

    Run the command from the directory where you created the app.json configuration file, for example:

    cd root/python-docs-samples/appengine/standard/hello_world/
    
    curl -X POST -T "app.json" -H "Content-Type: application/json" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions
    

    Where:

    • [MY_ACCESS_TOKEN] is the access token that you obtained to authorize your HTTP requests.
    • [MY_PROJECT_ID] is the ID of project where you want to deploy the version.

    Example response:

    {
      "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
      "metadata": {
        "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
        "insertTime": "2016-07-29T17:12:44.679Z",
        "method": "google.appengine.v1.Versions.CreateVersion",
        "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
        "user": "me@example.com"
      }
    }
    

    Where [MY_PROJECT_ID] is your Cloud Platform project ID.

  2. Verify that the version of the Hello World app was successfully deployed to your App Engine application:

    1. View the status of the actual deployment operation by using the name of the operation that was returned in the previous step as the name field in an HTTP GET method, for example:

      GET https://appengine.googleapis.com/v1/[OPERATION_NAME]
      

      Example cURL command:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/[OPERATION_NAME]
      

      Where:

      • [OPERATION_NAME] is the value of the name field that was returned in the previous step when you deployed the app, for example apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85.
      • [MY_ACCESS_TOKEN] is the access token that you obtained to authorize your HTTP requests.
      • [MY_PROJECT_ID] is the ID of project where you want to deploy the version.

      Example response:

      {
        "done": true,
        "metadata": {
          "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
          "endTime": "2016-07-29T17:13:20.424Z",
          "insertTime": "2016-07-29T17:12:44.679Z",
          "method": "google.appengine.v1.Versions.CreateVersion",
          "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
          "user": "me@example.com"
        },
        "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
        "response": {
          "@type": "type.googleapis.com/google.appengine.v1.Version",
          "creationTime": "2016-07-29T17:12:46.000Z",
          "deployer": "me@example.com",
          "id": "appengine-helloworld",
          "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
          "runtime": "python27",
          "servingStatus": "SERVING",
          "threadsafe": true,
        }
      }
      

      Where [MY_PROJECT_ID] is your Cloud Platform project ID.

    2. Verify that the version of the Hello World app was created in your App Engine application by using an HTTP GET request to view the version details, for example:

      GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL
      

      Example cURL command:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL
      

      Where:

      • [MY_ACCESS_TOKEN] is the access token that you obtained to authorize your HTTP requests.
      • [MY_PROJECT_ID] is the ID of project where you want to deploy the version.

      Example response:

      {
        "creationTime": "2016-07-29T17:12:46.000Z",
        "deployer": "me@example.com",
        "deployment": {
          "files": {
            "main.py": {
              "sha1Sum": "13f7ea1e24f7cd2de5c66660525f2b509da37c14",
              "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
            }
          }
        },
        "handlers": [
          {
            "authFailAction": "AUTH_FAIL_ACTION_REDIRECT",
            "login": "LOGIN_OPTIONAL",
            "script": {
              "scriptPath": "main.app",
            },
            "securityLevel": "SECURE_OPTIONAL",
            "urlRegex": "/.*"
          }
        ]
        "id": "appengine-helloworld",
        "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
        "runtime": "python27",
        "servingStatus": "SERVING",
        "threadsafe": true,
        "versionUrl": "https://appengine-helloworld-dot-[MY_PROJECT_ID].appspot.com"
      }
      

      Where [MY_PROJECT_ID] is your Cloud Platform project ID.

  3. View the Hello World app in your web browser by visiting the URL specified in the versionUrl field of the HTTP response of the previous step, for example:

    https://appengine-helloworld-dot-[MY_PROJECT_ID].appspot.com
    

    Where [MY_PROJECT_ID] is your Cloud Platform project ID.

  4. Configure traffic to the Hello World app.

    By default, the initial version that you deploy to a new App Engine application automatically receives 100% of traffic and any subsequent versions receive zero traffic.

    1. To view if your version is configured to receive traffic, you send an HTTP GET request, for example:

      GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
      

      Example cURL command:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
      

      Where:

      • [MY_ACCESS_TOKEN] is the access token that you obtained to authorize your HTTP requests.
      • [MY_PROJECT_ID] is the ID of project where you want to deploy the version.

      Example response:

      {
        "name": "apps/[MY_PROJECT_ID]/services/default/",
        "id": "default",
        "split": {
          "allocations": {
            "appengine-helloworld": 1
          }
        }
      }
      

      Where [MY_PROJECT_ID] is your Cloud Platform project ID.

    2. To move all traffic to a version, you send an HTTP PATCH request, for example:

      PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "appengine-helloworld": 1 } } }
      

      Example cURL command:

      curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'allocations': { 'appengine-helloworld': '1' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split
      

      Where:

      • [MY_ACCESS_TOKEN] is the access token that you obtained to authorize your HTTP requests.
      • [MY_PROJECT_ID] is the ID of project where you want to deploy the version.

      Example response:

      {
        "name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420",
        "metadata": {
          "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
          "insertTime": "2016-07-29T17:25:30.413Z",
          "method": "com.google.appengine.v1.Services.UpdateService",
          "target": "apps/[MY_PROJECT_ID]/services/default",
          "user": "me@example.com"
        }
      }
      

      Where [MY_PROJECT_ID] is your Cloud Platform project ID.

Extended learning

If you have more that one version of an app, you can perform the following steps to split traffic between those versions:

  1. To deploy a second version of the Hello World app to the same App Engine application:

    1. In the existing app.json configuration file of the Hello World app that you created earlier, update the id field to specify a different version. For example append a -2:

      "id": "appengine-helloworld-2"
      
    2. Perform all the same steps again to deploy a appengine-helloworld-2 version, for example:

      1. Authenticate with your project.
      2. Deploy the new appengine-helloworld-2 version.
      3. Verify that the appengine-helloworld-2 version was successfully deployed.
      4. View the running app in your web browser.
  2. Follow the instructions for splitting traffic in Migrating and Splitting Traffic, for example you send an HTTP PATCH request:

    PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }
    

    Example cURL command:

    curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split
    

    Where:

    • [MY_ACCESS_TOKEN] is the access token that you obtained to authorize your HTTP requests.
    • [MY_PROJECT_ID] is the ID of project where you want to deploy the version.

What's next

  • Create, configure, and then setup credentials for your applications: Accessing the API

Send feedback about...

App Engine Admin API