Getting Started with the Admin API

Region ID

The REGION_ID is an abbreviated code that Google assigns based on the region you select when you create your app. The code does not correspond to a country or province, even though some region IDs may appear similar to commonly used country and province codes. For apps created after February 2020, REGION_ID.r is included in App Engine URLs. For existing apps created before this date, the region ID is optional in the URL.

Learn more about region IDs.

OK

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 Google Cloud 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.

Tip: To play around and see what the API can do without writing any code or setting up projects and credentials, visit the APIs Explorer.

Objectives

• Enable the APIs in your Google Cloud 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.

Note: Typically, you must first create a Google Cloud Storage bucket and then upload a copy of your app before you can deploy it to App Engine with the Admin API. However, this guide uses Hello World app resources that have already been uploaded to a public Cloud Storage bucket. For more information about the deployment process, see Deploying Versions of Your App.

Before you begin

• You must have or create a Google Account.
• Download and install the Google Cloud CLI and then initialize the gcloud CLI:
  Download the SDK

Important: The steps and all the corresponding examples refer to the example Google Cloud project [MY_PROJECT_ID]. To run the commands against your project, you must replace all instances of [MY_PROJECT_ID] with your project ID.
For information about creating a Google Cloud project, see the instructions for your language: standard environment or flexible environment.

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

Configuring your Google Cloud project

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

1. Enable the APIs in the Google Cloud console:

   Enable the APIs

2. In the wizard, select an existing project from the list or click Continue to create a new project.

3. 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.

      Note: The redirect URI defines where the HTTP response is sent. The https://www.google.com URI is used in this guide as an example but for production, you must specify your application's auth endpoint, which handles responses from the OAuth 2.0 server.

   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 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

Note: Typically you use the convert_yaml.py tool to create a JSON formatted configuration file. You convert the app.yaml file of your app and then define all of the app's resources that you want to deploy from your Cloud Storage bucket. For more information about converting app.yaml files, see Deploying Versions To Your Application.

Authorizing HTTP requests

Authenticate with App Engine so that you can send HTTP requests with the Admin API.

Use either of the following options to help you quickly get started. Both the HTTPS and gcloud options provide you with manual, yet simple, steps for obtaining access tokens for the purposes of trying out the Admin API.

HTTPS

To simulate a client-side OAuth 2.0 flow, add your OAuth client ID credential to a URI, and then send the HTTPS request through your web browser:

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
   

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 Google Cloud project.

gcloud

To simply retrieve an access token, run the following gcloud commands:

1. Set the Application Default Credential (ADC) that you want to use for requesting an access token:

   gcloud auth application-default login
   

2. Request the access token:

   gcloud auth application-default print-access-token
   

For details about these commands, see gcloud auth application-default.

Remember: Your access token expires approximately 60 minutes after it is issued.

The options above are not intended for use in your programmatic implementation, but information about how to implement an OAuth 2.0 authorization flow is available in Accessing the Admin API.

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": "[e-mail]"
     }
   }
   

   Where [MY_PROJECT_ID] is your Google Cloud 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": "[e-mail]"
        },
        "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": "[e-mail]",
          "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 Google Cloud 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": "[e-mail]",
        "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].[REGION_ID].r.appspot"
      }
      

      Where [MY_PROJECT_ID] is your Google Cloud 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].[REGION_ID].r.appspot.com
   

   Where [MY_PROJECT_ID] is your Google Cloud project ID.

   The REGION_ID is an abbreviated code that Google assigns based on the region you select when you create your app. The code does not correspond to a country or province, even though some region IDs may appear similar to commonly used country and province codes. For apps created after February 2020, REGION_ID.r is included in App Engine URLs. For existing apps created before this date, the region ID is optional in the URL.

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 Google Cloud 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": "[e-mail]"
        }
      }
      

      Where [MY_PROJECT_ID] is your Google Cloud 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