• Официальный сайт SDK
  • Сайт с примерами кода

Настройка приложения

Каждое приложение платформы App Engine имеет конфигурационный файл, который расположен в его корневом каталоге и называется app.yaml. Этот файл описывает тип среды выполнения, используемую приложением, версию исходного кода и определяет схему URL и соответствующие скрипты-обработчики запросов. Файл app.yaml загружается на сервер одновременно с кодом самого приложения.

Ниже приведен пример файла app.yaml:

CmFwcGxpY2F0aW9uOiBteWFwcAp2ZXJzaW9uOiAxCnJ1bnRpbWU6IHB5dGhvbgphcGlfdmVyc2lvbjogMQpoYW5kbGVyczoKLSB1cmw6IC8Kc2NyaXB0OiBob21lLnB5Ci0gdXJsOiAvaW5kZXhcLmh0bWwKc2NyaXB0OiBob21lLnB5Ci0gdXJsOiAvc3R5bGVzaGVldHMKc3RhdGljX2Rpcjogc3R5bGVzaGVldHMKLSB1cmw6IC8oLipcLihnaWZ8cG5nfGpwZykpCnN0YXRpY19maWxlczogc3RhdGljL1wxCnVwbG9hZDogc3RhdGljLyguKlwuKGdpZnxwbmd8anBnKSkKLSB1cmw6IC9hZG1pbi8uKgpzY3JpcHQ6IGFkbWluLnB5CmxvZ2luOiBhZG1pbgotIHVybDogLy4qCnNjcmlwdDogbm90X2ZvdW5kLnB5Cg===

Данные в файле app.yaml указываются в формате разметки YAML. Для дополнительной информации об этом языке посетите сайт YAML.

Подсказка: Язык разметки YAML поддерживает использование комментариев. Все строки, начинающиеся с символа # будут проигнорированы:
# Это комментарий.

В шаблонах для URL используется расширенный синтаксис регулярных выражений POSIX, исключая сбор и обобщение элементов классов. Поддерживаются обратные ссылки и группы (например, 1), также как в расширениях языка Perl w W s S d D (Это похоже на синтаксис в Поиске кода, плюс поддержка обратных ссылок.)

Обязательные элементы

Файл app.yaml должен включать в себя следующие элементы:

application

Идентификатор приложения. Он задается единожды при создании нового приложения через Административную консоль.

YXBwbGljYXRpb246IG15YXBw=
version

Текущая версия исходного кода приложения. Платформа App Engine выполняет сохранение копии кода приложения для каждой заданной с помощью параметра version версии. Администратор может произвести изменение мажорной версии приложения с помощью Административной консоли и проводить тестирование бета-версий приложения перед тем, как сделать их доступным всем пользователям.

Каждая версия приложения имеет собственную копию файла app.yaml. При загрузке приложения на сервер, уже доступный ранее исходный код с совпадающей версией со значением в файле app.yaml заменяется на новый.

В Административной консоли версия приложения состоит из двух частей: мажорной версии (совпадающей с параметром version) и минорной, показывающей сколько раз была произведена загрузка приложения. Хранится код только каждой последней мажорной версии.

dmVyc2lvbjogMQ===
runtime

Тип среды выполнения платформы App Engine, используемый этим приложением. На текущий момент может иметь только значение: python

cnVudGltZTogcHl0aG9u=
api_version

Версия API данной среды выполнения, используемая этим приложением. Даже после того, как компания Google выпускает новые версии интерфейсов API, ваше приложение будет продолжать использовать именно ту версию, для которой оно было написано. Для миграции на новую версию API измените это значение и проведите повторную загрузку приложения.

На текущий момент App Engine имеет только одну версию API для среды выполнения python: 1

YXBpX3ZlcnNpb246IDE==
handlers

Список шаблонов адресов URL и описания соответствующих им способов обработки запросов. Платформа App Engine может при отправке запроса по указанному URL выполнить заданный код приложения или выдать статический файл, загруженный вместе с кодом, к примеру, изображения, стили CSS или JavaScript.

Все шаблоны обрабатываются в том порядке, в каком они были указаны в файле app.yaml - сверху вниз. Первый шаблон, удовлетворяющий выполненному запросу, используется для его обработки.

Существуют два типа обработчиков: скриптовые и статические файловые. Скриптовый обработчик выполняет запуск соответствующего скрипта языка Python, совпадающего с заданным URL. Статический обработчик передает в ответ на запрос статическое содержимое, такое как файл с изображением.

Смотрите ниже разделы Скриптовые обработчики и Обработчики статических файлов для дополнительной информации о формате этих значений.

aGFuZGxlcnM6Ci0gdXJsOiAvaW1hZ2VzCnN0YXRpY19kaXI6IHN0YXRpYy9pbWFnZXMKLSB1cmw6IC8uKgpzY3JpcHQ6IG15YXBwLnB5Cg===

Обработчики запросов

Скрипт-обработчик выполняет код на языке Python, который производит необходимые действия и выдает результат. В сопоставлении определяется шаблон адреса URL и соответствующий ему скрипт для выполнения.

url

Шаблон адреса URL, являющийся регулярным выражением. Выражение может содержать группировки, которые ссылаются на пути к файлам со скриптами-обработчиками.

К примеру, /profile/(.*?)/(.*) будет удовлетворять URL /profile/edit/manager и использовать значения edit и manager как первую и вторую группировку.

aGFuZGxlcnM6Ci0gdXJsOiAvcHJvZmlsZS8oLio/KS8oLiopCnNjcmlwdDogL2VtcGxveWVlL1wyL1wxLnB5Cg===
script

Путь к скрипту-обработчику относительно корневого каталога приложения.

Также как и в предыдущем примере, выражение заданное с группировками edit и manager, со скриптом /employee/2/1.py будет указывать на файл /employee/manager/edit.py.

Следующий пример сопоставляет адреса URL со скриптами-обработчиками:

CmhhbmRsZXJzOgojINCa0L7RgNC90LXQstC+0LkgVVJMICgvKSDQvtCx0YHQu9GD0LbQuNCy0LDQtdGC0YHRjyDRgdC60YDQuNC/0YLQvtC8IGluZGV4LnB5INCS0YHQtSDQtNGA0YPQs9C40LUgVVJMINC90LUg0LHRg9C00YPRgiDRg9C00L7QstC70LXRgtCy0L7RgNGP0YLRjCDRjdGC0L7QvNGDINGI0LDQsdC70L7QvdGDLgotIHVybDogLwpzY3JpcHQ6IGluZGV4LnB5CiMgVVJMIC9pbmRleC5odG1sINGC0LDQutC20LUg0L7QsdGA0LDQsdCw0YLRi9Cy0LDQtdGC0YHRjyDRgdC60YDQuNC/0YLQvtC8IGluZGV4LnB5Ci0gdXJsOiAvaW5kZXhcLmh0bWwKc2NyaXB0OiBpbmRleC5weQojINCg0LXQs9GD0LvRj9GA0L3QvtC1INCy0YvRgNCw0LbQtdC90LjQtSDQvNC+0LbQtdGCINCy0YvQv9C+0LvQvdGP0YLRjCDRgdC+0L/QvtGB0YLQsNCy0LvQtdC90LjQtSDRh9Cw0YHRgtC10Lkg0LDQtNGA0LXRgdCwIFVSTCDRgSDQuNC80LXQvdC10Lwg0L/Rg9GC0Lgg0Log0YHQutGA0LjQv9GC0YMuCi0gdXJsOiAvYnJvd3NlLyhib29rc3x2aWRlb3N8dG9vbHMpCnNjcmlwdDogXDEvY2F0YWxvZy5weQojINCS0YHQtSDQtNGA0YPQs9C40LUgVVJMINC40YHQv9C+0LvRjNC30YPRjtGCINGB0LrRgNC40L/RgiBub3RfZm91bmQucHkKLSB1cmw6IC8uKgpzY3JpcHQ6IG5vdF9mb3VuZC5weQo==

Обработчики статических файлов

Статические файлы (изображения, стили CSS и скрипты JavaScript) могут быть выданы пользователю напрямую без выполнения кода. Обработчики статических файлов определяют, какие файлы приложения являются статическими и по каким URL они будут доступны.

Для эффективности работы, App Engine хранит и работает со статическими файлами отдельно от файлов приложения. Таким образом они не доступны из файловой системы приложения. Если вам необходимо загрузить какие-то данные, к которым будет обращаться приложение, они не должны быть сопоставлены ни с одним шаблоном для статических файлов.

Если не указано иное, браузеры осуществляют кэширование скачиваемых данных и хранят их какое-то время. Вы можете глобально определить время кэширования для всего статического содержимого приложения, определив в конфигурации элемент верхнего уровня default_expiration. Также существует возможность задать период для определенного обработчика статических файлов. (Скрипты-обработчики могут сами устанавливать период кэширования результатов запросов в браузере, определяя соответствующие заголовки протокола HTTP)

default_expiration

Указывается время кэширования статического содержимого в браузере пользователя по умолчанию, за исключением случаев, когда в обработчике задан собственный параметр expiration. Это значение является строкой из чисел и метрик, разделенных пробелами, где метрика указывается как d для дней, h для часов, m для минут и s для секунд. К примеру, значение "4d 5h" задает устаревание данных через 4 дня и 5 часов, после того, как файл будет первый раз загружен браузером.

Параметр default_expiration является необязательным. Если он неопределен, то время кэширования зависит от настроек пользовательского браузера.

Например:

CmFwcGxpY2F0aW9uOiBteWFwcAp2ZXJzaW9uOiAxCnJ1bnRpbWU6IHB5dGhvbgphcGlfdmVyc2lvbjogMQpkZWZhdWx0X2V4cGlyYXRpb246ICI0ZCA1aCIKaGFuZGxlcnM6CiMgLi4uCg===

Обработчики статических файлов могут быть заданы двумя способами: как каталог с файлами, сопоставленный с определенным URL, или как шаблон URL, указывающий на конкретные файлы.

Обработчики статических каталогов

Обработчик статического каталога выполняет обслуживание запросов и рассматривает все файлы каталога как статические. Каждый тип файла связывается с MIME-типом, соответствующим расширению файла в том случае, если не задан перекрывающий параметр mime_type в определении каталога. Все файлы, содержащиеся в заданном каталоге, загружаются на сервер как статические и ни один из них не может выполняться как скрипт.

url

Префикс URL. Это значение использует синтаксис регулярного выражения (специальные символы обязательно должны быть экранированы), но оно не должно содержать группировки. Все URL, начинающиеся с этого префикса обслуживаются этим обработчиком, и используют для поиска файлов ту часть адреса, которая находится после префикса.

static_dir

Путь к каталогу, содержащему статические файлы, относительно корневого каталога приложения. Окончание шаблона, заданного в параметре url дополняется к значению static_dir и таким образом образуется полное имя файла.

Все файлы в этом каталоге считатся статическими.

mime_type

Необязательный параметр. Если он указан, все файлы, обслуживаемые этим обработчиком, передаются с указанием определенного MIME-типа. Если не указан, то MIME-тип каждого файла определяется на основании его расширения.

Для дополнительной информации о существующих MIME-типах посетите сайт IANA MIME Media Types.

expiration

Указывается время кэширования статического содержимого в браузере пользователя. Это значение является строкой из чисел и метрик, разделенных пробелами, где метрика указывается как d для дней, h для часов, m для минут и s для секунд. К примеру, значение "4d 5h" задает устаревание данных через 4 дня и 5 часов, после того, как файл будет первый раз загружен браузером.

Параметр expiration является необязательным. Если он не задан, используется глобальный параметр default_expiration.

Например:

CmhhbmRsZXJzOgojINCS0YHQtSBVUkwsINC90LDRh9C40L3QsNGO0YnQuNC10YHRjyDQvdCwIC9zdHlsZXNoZWV0cyDQv9GA0LXQvtCx0YDQsNC30L7QstGL0LLQsNGO0YLRgdGPINCyINC40LzQtdC90LAKIyDRgdGC0LDRgtC40YfQtdGB0LrQuNGFINGE0LDQudC70L7QsiDQsiDQutCw0YLQsNC70L7Qs9C1IHN0eWxlc2hlZXRzLyDQntCx0YDQsNGC0LjRgtC1INCy0L3QuNC80LDQvdC40LUsINGH0YLQviDQv9Cw0YDQsNC80LXRgtGAIHN0YXRpY19kaXIKIyDQvdC1INC80L7QttC10YIg0LHRi9GC0Ywg0YDQtdCz0YPQu9GP0YDQvdGL0Lwg0LLRi9GA0LDQttC10L3QuNC10LwsINGN0YLQviDRgtC+0LvRjNC60L4g0L/RgNC10YTQuNC60YEKLSB1cmw6IC9zdHlsZXNoZWV0cwpzdGF0aWNfZGlyOiBzdHlsZXNoZWV0cwo==

Обработчики шаблонов статических файлов

Обработчик статического файла ассоциирует шаблон URL с полным именем файла, включая его путь. Шаблон URL является регулярным выражением и может определять группировки, которые затем используются при формировании пути к файлу. Вы можете использовать эту конструкцию вместо static_dir для сопоставления файлов в произвольных каталогах приложения без выделения под них отдельного.

Статические файлы одновременно не могут быть файлами с кодом приложения. Если файл задан в обработчике статических файлов, то он никогда не будет использован как скрипт, даже в том случае, если совпадает с динамическим обработчиком.

Следующие конструкции static_dir и static_files эквивалентны:

Ci0gdXJsOiAvaW1hZ2VzCnN0YXRpY19kaXI6IHN0YXRpYy9pbWFnZXMKLSB1cmw6IC9pbWFnZXMvKC4qKQpzdGF0aWNfZmlsZXM6IHN0YXRpYy9pbWFnZXMvXDEKdXBsb2FkOiBzdGF0aWMvaW1hZ2VzLyguKikK=
url

Шаблон адреса URL, являющийся регулярным выражением. Выражение может содержать группировки, которые ссылаются на пути к файлам со скриптами-обработчиками.

К примеру, /item-(.*?)/category-(.*) будет удовлетворять URL /item-127/category-fruit и использовать значения 127 и fruit как первую и вторую группировку.

aGFuZGxlcnM6Ci0gdXJsOiAvaXRlbS0oLio/KS9jYXRlZ29yeS0oLiopCnN0YXRpY19maWxlczogYXJjaGl2ZXMvXDIvaXRlbXMvXDEK=
static_files

Путь к статическим файлам, совпадающим с этим шаблоном URL, относительно корневого каталога приложения. В пути может задаваться текст, совпадающий с группировками шаблонов URL.

Как и в предыдущем примере, шаблон archives/2/items/1 производит вставку второй и первой группировки соответственно вместо 2 и 1. В вышеприведенном примере шаблона, путь к файлу будет выглядеть: archives/fruit/items/127.

upload

Регулярное выражение, которое совпадает с именами файлов, сопоставленных с этим обработчиком. Этот параметр необходимо указывать так как обработчик не может определить какие файлы в каталоге приложения совпадают с шаблонами url и static_files. Статические файлы загружаются и обрабатываются отдельно от основных файлов приложения.

В приведенном выше примере можно использовать следующий шаблон upload: archives/(.*?)/items/(.*)

mime_type

Необязательный параметр. Если он указан, все файлы, обслуживаемые этим обработчиком, передаются с указанием определенного MIME-типа. Если не указан, то MIME-тип каждого файла определяется на основании его расширения.

Для дополнительной информации о существующих MIME-типах посетите сайт IANA MIME Media Types.

expiration

Указывается время кэширования статического содержимого в браузере пользователя. Это значение является строкой из чисел и метрик, разделенных пробелами, где метрика указывается как d для дней, h для часов, m для минут и s для секунд. К примеру, значение "4d 5h" задает устаревание данных через 4 дня и 5 часов, после того, как файл будет первый раз загружен браузером.

Параметр expiration является необязательным. Если он не задан, используется глобальный параметр default_expiration.

Например:

CmhhbmRsZXJzOgojINCS0YHQtSBVUkwsINC30LDQutCw0L3Rh9C40LLQsNGO0YnQuNC10YHRjyDQvdCwIC5naWYgLnBuZyDQuNC70LggLmpwZyDRgdC+0L/QvtGB0YLQsNCy0LvRj9GO0YLRgdGPCiMg0YEg0YTQsNC50LvQsNC80Lgg0LjQtyDQutCw0YLQsNC70L7Qs9CwIHN0YXRpYy8g0KjQsNCx0LvQvtC9IFVSTCDRj9Cy0LvRj9C10YLRgdGPINGA0LXQs9GD0LvRj9GA0L3Ri9C8INCy0YvRgNCw0LbQtdC90LjQtdC8LAojINCz0YDRg9C/0L/QuNGA0L7QstC60Lgg0LrQvtGC0L7RgNC+0LPQviDQstGB0YLQsNCy0LvRj9GO0YLRgdGPINCyINC40YLQvtCz0L7QstGL0Lkg0L/Rg9GC0Ywg0YTQsNC50LvQsC4KLSB1cmw6IC8oLipcLihnaWZ8cG5nfGpwZykpCnN0YXRpY19maWxlczogc3RhdGljL1wxCnVwbG9hZDogc3RhdGljLyguKlwuKGdpZnxwbmd8anBnKSkK=

Требование авторизации

Любой обработчик URL, который имеет в своих настройках параметр login, предоставляет доступ только авторизованным пользователям или администраторам приложения. При обнаружении платформой параметра login в соответствующем URL, обработчик сначала выполняет проверку, что пользователь авторизован с помощью своего аккаунта Google. Если это не так, то он перенаправляется на страницу входа Google и затем, после успешной авторизации или создания нового аккаунта, обратно на страницу приложения.

Если указан параметр login: required, после успешной авторизации обработчик как обычно производит выполнение запроса.

Если указан параметр login: admin, после авторизации пользователя, обработчик дополнительно проверяет, что он является администратором приложения. Если это не так, пользователь получает сообщение об ошибке. Если пользователь на самом деле администратор - обработчик продолжает дальше свою работу.

Если разработчику приложения требуется нестандартное решение, то он может самостоятельно реализовать этот функционал. Для дополнительной информации смотрите интерфейс Users API.

Пример:

CmhhbmRsZXJzOgotIHVybDogL3Byb2ZpbGUvLioKc2NyaXB0OiB1c2VyX3Byb2ZpbGUucHkKbG9naW46IHJlcXVpcmVkCi0gdXJsOiAvYWRtaW4vLioKc2NyaXB0OiBhZG1pbi5weQpsb2dpbjogYWRtaW4KLSB1cmw6IC8uKgpzY3JpcHQ6IHdlbGNvbWUucHkK=

Игнорирование файлов

Файлы приложения, пути к которым совпадают с определенными в параметрах static_dir или static_files upload считаются статическими файлами. Все другие файлы в каталоге приложения считаются файлами данных или кодом.

Элемент skip_files указывает на то, какие из файлов не нужно загружать на сервер App Engine вместе с приложением. Это значение является регулярным выражением. Любой файл, соответствующий ему, убирается из списка файлов, подлежащих публикации вместе с приложением.

Параметр skip_files по умолчанию имеет следующее значение:

CnNraXBfZmlsZXM6IHwKXiguKi8pPygKKGFwcFwueWFtbCl8CihhcHBcLnltbCl8CihpbmRleFwueWFtbCl8CihpbmRleFwueW1sKXwKKCMuKiMpfAooLip+KXwKKC4qXC5weVtjb10pfAooLiovUkNTLy4qKXwKKFwuLiopfAopJAo==

Значение по умолчанию исключает конфигурационные файлы app.yaml, app.yml, index.yaml, index.yml (конфигурация отправляется на сервер отдельно), файлы-бэкапы Emacs вида #...# и ...~, файлы .pyc и .pyo, файлы в каталоге RCS системы контроля версий и скрытые файлы Unix, начинающиеся на точку (.).

Новое значение, указанное в файле app.yaml, целиком перекрывает конфигурацию по умолчанию. Для того, чтобы дополнить существующие настройки, необходимо скопировать их и добавить свои исключения.

Ссылка на каталог с библиотекой Python

Вы можете сослаться на каталог с библиотекой языка Python при помощи параметра $PYTHON_LIB в файле app.yaml. Это удобно для подключения уже существующих в библиотеке App Engine обработчиков.

К примеру, $PYTHON_LIB/google/appengine/ext/admin является административным интерфейсом, подобный отладочной консоли сервера разработки, который можно сделать частью вашего приложения. Для его подключения, используйте следующее определение:

CmhhbmRsZXJzOgotIHVybDogL2FkbWluLy4qCnNjcmlwdDogJFBZVEhPTl9MSUIvZ29vZ2xlL2FwcGVuZ2luZS9leHQvYWRtaW4KbG9naW46IGFkbWluCg===

Зарезервированные URL

Некоторые URL зарезервированы платформой App Engine для административных целей. Адреса, сопоставленные с обработчиками приложения, никогда не должны указывать на эти пути.

Следующие URL являются зарезервированными:

  • /_ah/
  • /form