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.
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.
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.
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
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:
Enable the APIs in the Google Cloud console:
In the wizard, select an existing project from the list or click Continue to create a new project.
Click Continue to create an OAuth client ID credential:
- In the OAuth consent screen specify at least your Email address and the Product name shown to users.
- Save the consent screen settings and then switch to the Credentials tab by clicking Save.
- Click Create credentials and then OAuth client ID to create a client ID.
Click Web application, specify a name, and then use
https://www.google.com
as the redirect URI.Click Create to save the credential.
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
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:
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]
andredirect_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
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 theaccess_token
field to send HTTP requests to your Google Cloud project.
gcloud
To simply retrieve an access token, run the following gcloud
commands:
Set the Application Default Credential (ADC) that you want to use for requesting an access token:
gcloud auth application-default login
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:
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 Google Cloud project ID.Verify that the version of the Hello World app was successfully deployed to your App Engine application:
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 HTTPGET
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 thename
field that was returned in the previous step when you deployed the app, for exampleapps/[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 Google Cloud project ID.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].[REGION_ID].r.appspot" }
Where
[MY_PROJECT_ID]
is your Google Cloud project ID.
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.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.
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.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 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:
To deploy a second version of the Hello World app to the same App Engine application:
In the existing
app.json
configuration file of the Hello World app that you created earlier, update theid
field to specify a different version. For example append a-2
:"id": "appengine-helloworld-2"
Perform all the same steps again to deploy a
appengine-helloworld-2
version, for example:- Authenticate with your project.
- Deploy the new
appengine-helloworld-2
version. - Verify that the
appengine-helloworld-2
version was successfully deployed. - View the running app in your web browser.
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