This page describes how HTTP requests from users reach the appropriate version and instance of a service. Requests can be routed two ways:
- App Engine's default address 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 applications. When you are testing locally, the routing behavior depends on the particular runtime and development environment that you're using.
Requests and domains
App Engine determines that an incoming request is intended for your application
using the domain name of the request. A request whose domain name is
http://your_app_id.appspot.com is routed to the application whose ID is
your_app_id. Every application gets an
appspot.com domain name for free.
appspot.com domains also support subdomains of the form
subdomain can be any string
allowed in one part of a domain name (not
.). Requests sent to any subdomain
in this way are routed to your application.
You can set up a custom top-level domain using Google Apps. With Google Apps, you assign subdomains of your business's domain to various applications, such as Google Mail or Sites. You can also associate an App Engine application with a subdomain. For convenience, you can set up a Google Apps domain when you register your application ID, or later from the Cloud Platform Console. For more information, see Using Custom Domains and SSL.
Requests for these URLs all go to the version of your application that you have
selected as the default version in the Cloud Platform Console. Each version of
your application also has its own URL, so you can deploy and test a new version
before making it the default version. The version-specific URL uses the version
identifier from your app's configuration file in addition to the
domain name, in this pattern:
http://version_id-dot-latest-dot-your_app_id.appspot.com. You can also use
subdomains with the version-specific URL:
The domain name used for the request is included in the request data passed to
the application. If you want your app to respond differently depending on the
domain name used to access it (such as to restrict access to certain domains, or
redirect to an official domain), you can check the request data, such as the
Host request header, for the domain from within the application code and
Routing via URL
You can target an HTTP request with varying degrees of specificity. In the
appspot.com can be replaced with your app's custom domain
if you have one. The URL substrings "instance", "version", "service", and
"app-id" represent application and service attributes that you have defined.
These two address forms are guaranteed to reach their target (if it exists). They will never be intercepted and rerouted by a pattern in the dispatch file:
- Sends the request to the named service, version, and instance.
- Sends the request to an available instance of the named service and version.
These address forms have a default routing behavior. Note that the default routing is overridden if there is a matching pattern in the dispatch file:
- Sends the request to an available instance of the default version of the named service.
- Sends the request to an available instance of the given version of the default service.
- Sends the request to an available instance of the default version of the default service.
The default service is defined by explicitly giving a service the name "default," or by not including the name parameter in the service's config file. Requests that specify no service or an invalid service are routed to the default service. You can designate a default version for a service, when appropriate, in the Google Cloud Platform Console versions tab.
If a request matches the
app-id.appspot portion of the hostname, but includes
a service, version, or instance name that does not exist, then the request is
routed to the default version of the default service. Soft routing does not
apply to custom domains; requests to them will return a 404 if the
hostname is invalid.
Restricting access to a service
All services are public by default. If you want to restrict access to a service, add the “login: admin” parameter to its handlers.
Routing with a dispatch file
For certain URLs (described above), you can create a dispatch file that
overrides the routing rules. This lets you send incoming requests to a specific
service based on the path or hostname in the URL. For example, say that you want
to route mobile requests like
http://simple-sample.appspot.com/mobile/ to a
mobile frontend, route worker requests like
http://simple-sample.appspot.com/work/ to a static backend, and serve all
static content from the default service.
To do this you can create a custom routing with a
dispatch.yaml file. The file
can be placed in your project directory at the top level, or in the directory
that defines the default service.
dispatch: # Default module serves the typical web resources and all static resources. - url: "*/favicon.ico" module: default # Default module serves simple hostname request. - url: "simple-sample.appspot.com/" module: default # Send all mobile traffic to the mobile frontend. - url: "*/mobile/*" module: mobile-frontend # Send all work to the one static backend. - url: "*/work/*" module: static-backend
The dispatch file can contain up to 20 routing rules. When specifying the URL string, neither the hostname nor the path can be longer than 100 characters.
As you can see,
dispatch.yaml includes support for glob characters; however,
YAML syntax requires that you include such expressions in quotes to denote they
are strings. Glob characters can be used only before the hostname and at the end
of the path. If you prefer general routing rules that match many possible
requests, you could specify the following:
# Send any path that begins with “simple-sample.appspot.com/mobile” to the mobile-frontend module. - url: "simple-sample.appspot.com/mobile*" module: mobile-frontend # Send any domain/sub-domain with a path that starts with “work” to the static backend module. - url: "*/work*" module: static-backend
You can also write expressions that are more strict:
# Matches the path "/fun", but not "/fun2" or "/fun/other" - url: "*/fun" module: mobile-frontend # Matches the hostname 'customer1.myapp.com', but not '1.customer1.myapp.com. - url: "customer1.myapp.com/*" module: static-backend