Авторизация
Все запросы к API библиотеки Google Фото должны быть авторизованы авторизованным пользователем.
Детали процесса авторизации для OAuth 2.0 немного различаются в зависимости от того, какое приложение вы пишете. Следующий общий процесс применим ко всем типам приложений:
- Подготовьтесь к процессу авторизации, выполнив следующие действия:
- Зарегистрируйте свое приложение с помощью консоли Google API .
- Активируйте API библиотеки и получите данные OAuth, такие как идентификатор клиента и секрет клиента. Дополнительные сведения см. в разделе Начало работы .
- Для доступа к пользовательским данным приложение делает запрос в Google на определенную область доступа.
- Google отображает пользователю экран согласия, который просит его разрешить приложению запрашивать некоторые его данные.
- Если пользователь одобряет, Google предоставляет приложению токен доступа, срок действия которого истекает через короткий период времени.
- Приложение делает запрос пользовательских данных, прикрепляя к запросу токен доступа.
- Если Google определяет, что запрос и токен действительны, он возвращает запрошенные данные.
Чтобы определить, какие области подходят для вашего приложения, см. раздел Области авторизации .
Процесс для некоторых типов приложений включает дополнительные шаги, такие как использование токенов обновления для получения новых токенов доступа. Подробную информацию о потоках для различных типов приложений см. в разделе Использование OAuth 2.0 для доступа к API Google .
Кэширование
Сохраняйте данные свежими.
Если вам необходимо временно хранить медиафайлы (например, миниатюры, фотографии или видео) из соображений производительности, не кэшируйте их дольше 60 минут в соответствии с нашими рекомендациями по использованию.
Вам также не следует хранить baseUrls , срок действия которых истекает примерно через 60 минут.
Идентификаторы мультимедийных элементов и идентификаторы альбомов, которые однозначно идентифицируют контент в библиотеке пользователя, освобождаются от ограничения кэширования. Вы можете хранить эти идентификаторы неограниченное время (в соответствии с политикой конфиденциальности вашего приложения). Используйте идентификаторы медиа-элементов и идентификаторы альбомов, чтобы снова получить доступные URL-адреса и данные, используя соответствующие конечные точки. Дополнительные сведения см. в разделах «Получение медиа-элемента» или «Список альбомов» .
Если вам нужно обновить много элементов мультимедиа, возможно, будет более эффективно сохранить параметры поиска, которые вернули элементы мультимедиа, и повторно отправить запрос для перезагрузки данных.
SSL-доступ
HTTPS требуется для всех запросов веб-службы Library API, использующих следующий URL-адрес:
https://photoslibrary.googleapis.com/v1/service/output?parameters
Запросы, сделанные через HTTP, отклоняются.
Обработка ошибок
Информацию о том, как обрабатывать ошибки, возвращаемые API, см. в разделе Обработка ошибок Cloud API.
Повтор неудачных запросов
Клиенты должны повторить попытку при ошибках 5xx с экспоненциальной задержкой, как описано в разделе «Экспоненциальная отсрочка» . Минимальная задержка должна составлять 1 s если не указано иное.
В случае ошибки 429 клиент может повторить попытку с задержкой не менее 30s . При всех остальных ошибках повторная попытка может быть неприменима. Убедитесь, что ваш запрос идемпотентен, и ознакомьтесь с сообщением об ошибке.
Экспоненциальный откат
В редких случаях при обработке вашего запроса что-то может пойти не так. Вы можете получить код ответа HTTP 4XX или 5XX , или где-то между вашим клиентом и сервером Google может произойти сбой TCP-соединения. Часто имеет смысл повторить запрос. Последующий запрос может быть успешным, если исходный запрос не удался. Однако важно не зацикливаться и неоднократно отправлять запросы к серверам Google. Такое зацикливание может перегрузить сеть между вашим клиентом и Google и вызвать проблемы для многих сторон.
Лучший подход — повторить попытку с увеличением задержки между попытками. Обычно задержка увеличивается на мультипликативный коэффициент с каждой попыткой — подход, известный как экспоненциальная задержка .
Также следует следить за тем, чтобы в цепочке вызовов приложения не было кода повтора, который приводит к быстрым последовательным повторным запросам.
Вежливое использование Google API
Плохо спроектированные клиенты API могут создавать большую нагрузку, чем необходимо, как в Интернете, так и на серверах Google. В этом разделе приведены некоторые рекомендации для клиентов API. Следование этим рекомендациям поможет вам избежать блокировки вашего приложения из-за непреднамеренного злоупотребления API.
Синхронизированные запросы
Большое количество синхронизированных запросов к API Google может выглядеть как распределенная атака типа «отказ в обслуживании» (DDoS) на инфраструктуру Google, и к ним следует относиться соответствующим образом. Чтобы этого избежать, следует убедиться, что запросы API не синхронизированы между клиентами.
Например, рассмотрим приложение, которое отображает время в текущем часовом поясе. Это приложение, вероятно, установит будильник в клиентской операционной системе, пробуждая ее в начале минуты, чтобы отображаемое время можно было обновить. Приложение не должно выполнять никаких вызовов API в рамках обработки, связанной с этим сигналом тревоги.
Выполнение вызовов API в ответ на фиксированный сигнал тревоги — это плохо, поскольку это приводит к тому, что вызовы API синхронизируются с началом минуты, даже между разными устройствами, а не распределяются равномерно во времени. Плохо спроектированное приложение, делающее это, вызывает всплеск трафика, в шестьдесят раз превышающий нормальный уровень в начале каждой минуты.
Вместо этого один из возможных хороших вариантов — установить второй будильник на случайно выбранное время. Когда срабатывает второй сигнал тревоги, приложение выполняет вызовы любых необходимых ему API и сохраняет результаты. Чтобы обновить свое отображение в начале минуты, приложение использует ранее сохраненные результаты вместо повторного вызова API. При таком подходе вызовы API распределяются равномерно во времени. Кроме того, вызовы API не задерживают рендеринг при обновлении дисплея.
Помимо начала минуты, другие распространенные моменты синхронизации, которые следует избегать, — это начало часа и начало каждого дня в полночь.