Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
App Engine builds and executes Go application code using a safe "sandboxed" environment. Your app receives web requests, performs work, and sends responses by interacting with this environment.
App Engine knows to use the Go runtime environment for your application code
when you use the tool named appcfg.py
from the Go SDK with a
configuration file named app.yaml
. You select the Go runtime
environment using the following configuration elements:
runtime: go api_version: 3
The first element, runtime
, selects the Go runtime
environment.
The second element, api_version
, selects which version of the Go
runtime environment to use. As of this writing, the most recent version of
the Go environment is 3
.
The version identifier will be incremented when the App Engine team releases
changes to the environment that may not be compatible with existing code.
This means you can continue to use the older APIs until you are able to
update your app and change the api_version
setting.
During the Go runtime's "experimental" phase, the App Engine team may change
the APIs in backwards-incompatible ways without updating the api_version
. Please subscribe to the
google-appengine-go
mailing list to be notified of any significant API changes.
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.your_app_id.appspot.com
, where 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 Administrator Console. See Deploying your Application on your Google Apps URL for more information.
Requests for these URLs all go to the version of your application that you have selected as the default version in the Administration 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 appspot.com
domain name, in this pattern: http://version_id.latest.your_app_id.appspot.com
You can also use subdomains with the version-specific URL: http://subdomain.version_id.latest.your_app_id.appspot.com
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 respond accordingly.
If your app uses backends, you can address requests to a specific backend and a specific instance with that backend. For more information about backend addressability, please see Properties of Backends.
The App Engine Go API uses the standard
http package
as an interface between your Go program and the App Engine servers.
When App Engine receives a web request for your application, it invokes the
http.Handler
associated with the request URL.
(The URL must also be specified as a Go handler in the application's
app.yaml
configuration file.)
App Engine uses multiple web servers to run your application, and automatically adjusts the number of servers it is using to handle requests reliably. A given request may be routed to any server, and it may not be the same server that handled a previous request from the same user. Multiple requests may be handled concurrently by a given server.
The following example is a complete Go app that outputs a hard-coded HTML string to the user.
package hello import ( "fmt" "http" ) func init() { http.HandleFunc("/", hello) } func hello(w http.ResponseWriter, r *http.Request) { fmt.Fprintf(w, "<h1>Hello, world</h1>") }
An incoming HTTP request includes the HTTP headers sent by the client. For security purposes, some headers are sanitized or amended by intermediate proxies before they reach the application.
As a service to the app, App Engine adds an additional header: X-AppEngine-Country
This header's value represents the country from which the request originated, as an ISO 3166-1 alpha-2 country code. App Engine determines this code from the client's IP address.
App Engine calls the handler with a Request
and a
ResponseWriter
, then waits for the handler to write to the
ResponseWriter
and return. When the handler returns, the data in
the ResponseWriter
's internal buffer is sent to the user.
This is practically the same as when writing normal Go programs that use the http package. The one notable difference is that App Engine does not support streaming data in response to a single request.
If the client sends HTTP headers with the request indicating that the client can accept compressed (gzipped) content, App Engine compresses the response data automatically and attaches the appropriate response headers. It uses both the Accept-Encoding
and User-Agent
request headers to determine if the client can reliably receive compressed responses. Custom clients can force content to be compressed by specifying both Accept-Encoding
and User-Agent
headers with a value of "gzip".
If you access your site while signed in using an administrator account, App Engine includes per-request statistics in the response headers. The header X-AppEngine-Estimated-CPM-US-Dollars
represents an estimate of what 1,000 requests similar to this request would cost in US dollars. The header X-AppEngine-Resource-Usage
represents the resources used by the request, including server-side time as a number of milliseconds.
A request handler has a limited amount of time to generate and return a response to a request, typically around 60 seconds. Once the deadline has been reached, the request handler is interrupted.
When a Go request handler exceeds the deadline, its process is terminated and the runtime environment returns an HTTP 500 server error to the client.
While a request can take as long as 60 seconds to respond, App Engine is optimized for applications with short-lived requests, typically those that take a few hundred milliseconds. An efficient app responds quickly for the majority of requests. An app that doesn't will not scale well with App Engine's infrastructure.
To allow App Engine to distribute requests for applications across multiple web servers, and to prevent one application from interfering with another, the application runs in a restricted "sandbox" environment. In this environment, the application can execute code, store and query data in the App Engine datastore, use the App Engine mail, URL fetch and users services, and examine the user's web request and prepare the response.
An App Engine application cannot:
The Go runtime restricts the use of standard library packages that would
violate the sandbox policies. Such functions have been replaced by stubs that
return an os.EPERM
error or removed entirely.
The Go API's Context
object has Debugf
methods that send log messages
to the App Engine web server.
,
Infof,
Warningf,
Errorf, and
Criticalf
Log data for your application can be viewed and analyzed using the Administration Console, or downloaded using appcfg.py request_logs.
The following example demonstrates an HTTP handler that constructs an
appengine.Context
object from the *http.Request
and
logs the requested URL.
package hello import ( "appengine" "http" ) func init() { http.HandleFunc("/", Logger) } func Logger(w http.ResponseWriter, r *http.Request) { c := appengine.NewContext(r) c.Infof("Requested URL: %v", r.URL) }
The Go runtime provides access to environment information through the
appengine.Context
interface.
See the
appengine
package reference
for details.
Google App Engine allocates resources to your application automatically as traffic increases to support many simultaneous requests. However, App Engine reserves automatic scaling capacity for applications with low latency, where the application responds to requests in less than one second. Applications with very high latency (over one second per request for many requests) are limited by the system, and require a special exemption in order to have a large number of simultaneous dynamic requests. If your application has a strong need for a high throughput of long-running requests, you can request an exemption from the simultaneous dynamic request limit. The vast majority of applications do not require any exemption.
Applications that are heavily CPU-bound may also incur some additional latency in order to efficiently share resources with other applications on the same servers. Requests for static files are exempt from these latency limits.
Each incoming request to the application counts toward the Requests limit.
Data sent in response to a request counts toward the Outgoing Bandwidth (billable) limit.
Both HTTP and HTTPS (secure) requests count toward the Requests, Incoming Bandwidth (billable), and Outgoing Bandwidth (billable) limits. The Quota Details page of the Admin Console also reports Secure Requests, Secure Incoming Bandwidth, and Secure Outgoing Bandwidth as separate values for informational purposes. Only HTTPS requests count toward these values.
For more information on system-wide safety limits, see Limits, and the "Quota Details" section of the Admin Console.
In addition to system-wide safety limits, the following limits apply specifically to the use of request handlers:
Limit | Amount |
---|---|
request size | 32 megabytes |
response size | 32 megabytes |
request duration | 60 seconds |
maximum total number of files (app files and static files) | 10,000 total 1,000 per directory |
maximum size of an application file | 32 megabytes |
maximum size of a static file | 32 megabytes |
maximum total size of all application and static files | 150 megabytes |