The dispatch.yaml
allows you to override routing
rules.
You can use the dispatch.yaml
to send incoming requests to a specific service
(formerly known as modules) based on the path or hostname in the URL.
For more information, see How Requests are Routed.
Deploying the dispatch file
The dispatch.yaml
file should reside in the root
directory or in the
directory that defines the default service.
To deploy the dispatch.yaml
file, use the following command. Before you
deploy your dispatch file, you must ensure that all the services defined in that
file have already been deployed to App Engine.
gcloud
Run the gcloud app deploy
command from
the directory that contains the dispatch.yaml
:
gcloud app deploy dispatch.yaml
appcfg
Run the
appcfg update_dispatch
command from the directory that contains the dispatch.yaml
file and use
the -A
option to specify your Google Cloud project ID:
appcfg.py -A [YOUR_PROJECT_ID] update_dispatch .
Note that the dispatch.yaml
file is also deployed when you update a
service with the appcfg.py update
command.
For more information about the deployment commands, see Deploying a PHP 5 App.
Syntax
The root element in thedispatch.yaml
file is dispatch:
and contains a list
of routing definitions that are specified by the following subelements.
The rules that you define in your dispatch file must use HTTP URL patterns
that include the ".
" notation for separating subdomains. URLs
defined with the HTTPS "-dot-
" notation are not supported.
Dispatch rules are order dependent, and can also apply to the URLs that you define in your cron file.
Element | Description |
---|---|
service |
Specifies the name of the service that will handle the requests that
match the |
url |
In the
Tip: You can include glob patterns like the A URL pattern that can include the hostname and URL path. Glob characters can be used to match patterns. The Glob characters can be specified only at the beginning of the pattern and end of the pattern. Note that dispatch rules also apply to URLs that are used in cron configuration or in task queue configuration.
URL paths that begin with |
Example
The following is a sample dispatch file that routes requests to
http://simple-sample.appspot.com
and requests like
http://simple-sample.appspot.com/favicon.ico
to the default
service. All
static content is served from the default
service. Mobile requests like
http://simple-sample.appspot.com/mobile/
are routed to a mobile frontend, and
worker requests like http://simple-sample.appspot.com/work/
are routed to a
static backend.
dispatch:
# Default service serves the typical web resources and all static resources.
- url: "*/favicon.ico"
service: default
# Default service serves simple hostname request.
- url: "simple-sample.appspot.com/"
service: default
# 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
If you prefer general routing rules that match many possible requests, you can define rules with wider scopes. For example:
# Send any path that begins with “simple-sample.appspot.com/mobile” to the mobile-frontend service.
- url: "simple-sample.appspot.com/mobile*"
service: mobile-frontend
# Send any domain/sub-domain with a path that starts with “work” to the static backend service.
- url: "*/work*"
service: static-backend
You can also write expressions that are more strict:
# Matches the path "/fun", but not "/fun2" or "/fun/other"
- url: "*/fun"
service: mobile-frontend
# Matches the hostname 'customer1.myapp.com', but not '1.customer1.myapp.com.
- url: "customer1.myapp.com/*"
service: static-backend
Limits
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.
Deleting all dispatch rules
To delete all dispatch rules:
Edit the contents of the
dispatch.yaml
file to:dispatch:
Deploy the
dispatch.yaml
file to App Engine.