Region ID
The REGION_ID
is a code that Google assigns based on
the region you select when you create your app. Including
REGION_ID.r
in App Engine URLs is optional for
existing apps and will soon be required for all new apps.
Learn more about region IDs.
This page describes how HTTP requests from users reach the appropriate version of a service. Requests can be routed two ways:
App Engine's default routing rules apply to requests with a URL that ends at the domain level.
Alternatively, you can use a dispatch file that routes specific URL patterns according to your own rules.
These options apply only to deployed apps. When you are testing locally, the routing behavior depends on the particular runtime and development environment that you're using.
Requests and domains
Once your app is running in App Engine, you can use the following URL to
send HTTP requests to the app:
https://PROJECT_ID.REGION_ID.r.appspot.com
where
PROJECT_ID
is the ID of the Google Cloud project
that contains the app.
This URL sends requests to the version of your app that you have configured to receive traffic.
Each version of your app also has its own URL, so you can deploy and test a new
version before configuring that version to receive traffic. The version-specific
URL uses the ID of a specific version in addition to the project ID, region ID,
and appspot.com
domain name. For example:
https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com
.
Subdomains
The appspot.com
domains also support subdomains of the form
SUBDOMAIN-dot-PROJECT_ID.REGION_ID.r.appspot.com
,
where SUBDOMAIN
can be any string allowed in
one part of a domain name, excluding the .
character. Requests that are sent
to any subdomain in this way are routed to your app.
You can also use subdomains with a version-specific URL:
https://SUBDOMAIN-dot-VERSION_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com
.
See Routing via URL for more information and examples.
Custom domains
You can set up a custom top-level domain using G Suite and then assign subdomains to various apps, such as Google Mail or Sites. You can also associate an App Engine app with a subdomain. For more information about mapping a custom domain to your app, see Securing Custom Domains with SSL.
Domain name is included in the request data
The domain name used for the request is included in the request data that is
passed to your app. Therefore, you can use the request data to control how your
app responds based on the domain name in the request. For example, if you want
to redirect to an official domain, you can code your app to check the Host
request header and then respond accordingly based on the domain name.
Region ID
The REGION_ID
is a code that Google assigns based on
the region you select when you create your app. Including
REGION_ID.r
in App Engine URLs is optional for
existing apps and will soon be required for all new apps.
You can use the following tools to see the region ID of your app:
Console
In the Cloud Console, you can view the URLs for your app's Instances, Services, and Versions.
All of these URLs include the region ID.
gcloud
When you deploy an app or service, the gcloud app deploy
command
displays the URL after the deployment succeeds. This URL includes the
region ID.
To view the URL for a service that is already deployed:
Enter the
gcloud app versions list
command to list the versions of a specific service. For example, to list the versions of the default service, entergcloud app versions list --service=default
.Enter the
gcloud app versions describe
command. The output of that command includes the version URL with the app's region ID. For example, to describe version 20191023t101741 for the default service, entergcloud app versions describe 20191023t101741 --service=default
Routing via URL
You can target an HTTP request with varying degrees of specificity. In the
following examples, REGION_ID.r.appspot.com
can be replaced with your app's
custom domain if you have one. The URL substrings
VERSION_ID
, SERVICE_ID
,
and PROJECT_ID
, each represent the resource IDs of your app.
You can use the following tools to retrieve the IDs of your app's resources:
Console
In the Cloud Console, you can view the corresponding Instances, Services, and Versions pages.
gcloud
Run the
gcloud app instances list
command to list the resource IDs within a specific Google Cloud project.
API
To programmatically retrieve resource IDs, see the list
methods in the
Admin API.
Default routing
The following URL patterns have a default routing behavior. Note that the default routing is overridden if there is a matching pattern that you have defined in your dispatch file:
- Sends the request to an available instance of the
default
service: https://PROJECT_ID.REGION_ID.r.appspot.com
https://CUSTOM_DOMAIN
Requests are received by any version that is configured for traffic in the
default
service.- Sends the request to an available instance of the
- Sends a request to an available instance of a specific service:
https://SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com
https://SERVICE_ID.CUSTOM_DOMAIN
Requests are received by any version that is configured for traffic in the targeted service. If the service that you are targeting does not exist, the request gets soft routed.
- Sends a request to an available instance of a specific version in the
default
service:https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com
https://VERSION_ID.CUSTOM_DOMAIN
When a service is not targeted, requests are sent to the
default
service.
Soft routing
If a request matches the
PROJECT_ID.REGION_ID.r.appspot.com
portion of
the hostname, but includes a service, version, or instance name that does not
exist, then the request is routed to the default
service. Soft routing does
not apply to custom domains; requests to them will return a HTTP 404
status
code if the hostname is invalid.
Targeted routing
The following URL patterns are guaranteed to reach their target, if they exist. These requests are never intercepted and rerouted by the patterns that you have defined in your dispatch file:
- Sends the request to an available instance of a specific service and
version:
https://VERSION_ID-dot-SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com
https://VERSION_ID.SERVICE_ID.PROJECT_ID.CUSTOM_DOMAIN
Default service
The default
service is created when you deploy the initial version of your
app to App Engine. Requests that specify no service or
an invalid service are routed to the default
service. Those requests are then
handled by the versions that you have configured to receive traffic within the
default
service. You can see which versions are configured for traffic in the
Versions page
of the Cloud Console.
Example
To help demonstrate the URL patterns, assume an example Google Cloud project
with ID requestsProject
exists and includes an app that is running two
services and versions. The example app's default
service includes version
vFrontend
, and the second service service2
, includes version
vBackend
. Google has assigned uc
as the region ID for both apps.
To target specific services and versions, you can use the following URL patterns:
To target the version in the
default
service using HTTPS, you can use:https://vFrontend-dot-default-dot-requestsProject.uc.r.appspot.com https://vFrontend-dot-requestsProject.uc.r.appspot.com
To target the
vBackend
version using a custom domain, you can use:https://vBackend.service2.example.net https://vBackend.example.net
where
requestsProject.uc.r.appspot.com
is mapped to theexample.net
domain.
Routing with a dispatch file
For URLs that use the patterns described earlier, you can create a dispatch file to override App Engine's routing rules and define your own custom routing rules. With a dispatch file, you can send incoming requests to a specific service based on the path or host name in the request URL.
For details about creating a dispatch file, see the
dispatch.yaml
reference.
Creating a dispatch file
The dispatch file should be placed
either in the root of your project directory, or in the root
directory of your default
service.
You can define up to 20 routing rules in the dispatch file and each rule
consists of both the service
and url
elements.
For example, you can create a dispatch file to route mobile requests like
https://simple-sample.uc.r.appspot.com/mobile/
to a mobile frontend, and route worker
requests like https://simple-sample.uc.r.appspot.com/work/
to a static backend:
dispatch:
# Send all mobile traffic to the mobile frontend.
- url: "*/mobile/*"
service: mobile-frontend
# Send all work to the one static backend.
- url: "*/work/*"
service: static-backend
For details about how to define your dispatch.yaml, see the dispatch.yaml
reference documentation.
Deploying the dispatch file
To deploy the dispatch configuration file, run the following command:
gcloud
gcloud app deploy dispatch.yaml