Лучшие практики

Авторизация

Все запросы к API библиотеки Google Фото должны быть авторизованы пользователем, прошедшим проверку подлинности.

Детали процесса авторизации для OAuth 2.0 немного различаются в зависимости от того, какое приложение вы пишете. Следующий общий процесс применяется ко всем типам приложений:

  1. Подготовьтесь к процессу авторизации, выполнив следующие действия:
    • Зарегистрируйте свое приложение с помощью Google API Console .
    • Активируйте API библиотеки и получите данные OAuth, такие как идентификатор клиента и секрет клиента. Дополнительные сведения см. в разделе Начало работы .
  2. Чтобы получить доступ к пользовательским данным, приложение делает запрос в Google для определенной области доступа.
  3. Google отображает экран согласия для пользователя, который просит их разрешить приложению запрашивать некоторые из их данных.
  4. Если пользователь одобряет, Google предоставляет приложению токен доступа, срок действия которого истекает через короткий промежуток времени.
  5. Приложение делает запрос пользовательских данных, присоединяя к запросу токен доступа.
  6. Если Google определяет, что запрос и токен действительны, он возвращает запрошенные данные.

Чтобы определить, какие области подходят для вашего приложения, см. Область авторизации .

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

Кэширование

Сохраняйте данные свежими.

Если вам нужно временно хранить медиафайлы (например, эскизы, фотографии или видео) по соображениям производительности, не кэшируйте их дольше 60 минут в соответствии с нашими рекомендациями по использованию.

Вы также не должны хранить baseUrls , срок действия которых истекает примерно через 60 минут.

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

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

SSL-доступ

HTTPS требуется для всех запросов веб-служб API библиотек по следующему URL-адресу:

https://photoslibrary.googleapis.com/v1/service/output?parameters

Запросы, сделанные через HTTP, отклоняются.

Обработка ошибок

Сведения о том, как обрабатывать ошибки, возвращаемые API, см. в разделе Обработка ошибок облачных API.

Повтор неудачных запросов

Клиенты должны повторить попытку при ошибках 5xx с экспоненциальной отставкой, как описано в разделе «Экспоненциальная отсрочка» . Минимальная задержка должна составлять 1 s , если не указано иное.

Для ошибок 429 клиент может повторить попытку с минимальной задержкой в 30s секунд. Для всех других ошибок повторная попытка может быть неприменима. Убедитесь, что ваш запрос является идемпотентным, и см. сообщение об ошибке.

Экспоненциальная отсрочка

В редких случаях что-то может пойти не так при обработке вашего запроса. Вы можете получить код ответа HTTP 4XX или 5XX , или где-то между вашим клиентом и сервером Google может произойти сбой TCP-соединения. Часто имеет смысл повторить запрос. Последующий запрос может быть выполнен успешно, если первоначальный не удалось. Однако важно не зацикливаться, повторно отправляя запросы к серверам Google. Такое зацикливание может привести к перегрузке сети между вашим клиентом и Google и вызвать проблемы у многих сторон.

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

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

Вежливое использование API Google

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

Синхронизированные запросы

Большое количество синхронизированных запросов к API Google может выглядеть как атака распределенного отказа в обслуживании (DDoS) на инфраструктуру Google и рассматриваться соответствующим образом. Чтобы избежать этого, вы должны убедиться, что запросы API не синхронизируются между клиентами.

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

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

Вместо этого один из возможных хороших вариантов — установить второй будильник на случайно выбранное время. Когда срабатывает этот второй сигнал тревоги, приложение выполняет вызовы любых необходимых ему API-интерфейсов и сохраняет результаты. Чтобы обновить свое отображение в начале минуты, приложение использует ранее сохраненные результаты, а не снова вызывает API. При таком подходе вызовы API равномерно распределяются по времени. Кроме того, вызовы API не задерживают рендеринг при обновлении дисплея.

Помимо начала минуты, другие распространенные моменты синхронизации, на которые следует обратить внимание, — это начало часа и начало каждого дня в полночь.