Publishing API сервисов Play Games позволяет загружать изображения для ресурсов игры.
Варианты загрузки
API публикации сервисов Play Games позволяет загружать определенные типы двоичных данных или медиафайлов. Конкретные характеристики данных, которые можно загрузить, указаны на справочной странице для любого метода, поддерживающего загрузку медиаконтента:
Максимальный размер загружаемого файла. Максимальный объем данных, который можно хранить с помощью этого метода.
Допустимые MIME-типы медиафайлов. Типы двоичных данных, которые можно хранить с помощью этого метода.
Запросы на загрузку можно отправлять следующими способами: Укажите метод, который вы используете, с помощью параметра запроса uploadType.
Простая загрузка:
uploadType=media. Для быстрой передачи небольших файлов, например размером до 5 МБ.Многочастная загрузка:
uploadType=multipart. Для быстрой передачи небольших файлов и метаданных. Передает файл вместе с метаданными, описывающими его, в одном запросе.Возобновляемая загрузка:
uploadType=resumable. Для надежной передачи, особенно важных файлов большого размера. В этом случае вы используете запрос на инициацию сеанса, который может содержать метаданные. Это хороший вариант для большинства приложений, поскольку он также подходит для небольших файлов, хотя и требует одного дополнительного HTTP-запроса на загрузку.
При загрузке медиафайлов используется специальный URI. Методы, поддерживающие загрузку медиаконтента, имеют две конечные точки URI:
URI /upload для медиафайла. Формат конечной точки загрузки – стандартный URI ресурса с префиксом /upload. Используйте этот URI при передаче самих медиаданных.
Пример:
POST /upload/games/v1configuration/images/resourceId/imageType/imageTypeСтандартный URI ресурса для метаданных. Если ресурс содержит поля данных, они используются для хранения метаданных, описывающих загруженный файл. Этот URI можно использовать при создании или обновлении значений метаданных.
Пример:
POST /games/v1configuration/images/resourceId/imageType/imageType
Простая загрузка
Самый простой способ загрузить файл – отправить запрос на загрузку. Этот вариант подходит, если:
Файл достаточно мал, чтобы его можно было загрузить целиком, если соединение будет разорвано.
Нет метаданных для отправки. Это может быть полезно, если вы планируете отправить метаданные для этого ресурса в отдельном запросе или если метаданные не поддерживаются или недоступны. Чтобы использовать простую загрузку, отправьте запрос POST или PUT к URI /upload метода и добавьте параметр запроса uploadType=media. Пример:
POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media
HTTP-заголовки, которые используются при отправке простого запроса на загрузку, включают:
Content-Type. Укажите один из допустимых типов медиаданных для загрузки, перечисленных в справочнике Publishing API.Content-Length. Укажите количество загружаемых байтов. Необязательно, если вы используете передачу данных по частям.
Пример: простая загрузка
В примере ниже показан простой запрос на загрузку для Play Games Services Publishing API.
POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/png
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token
PNG data
Если запрос выполнен успешно, сервер возвращает код статуса HTTP 200 OK вместе с метаданными. Пример:
HTTP/1.1 200
Content-Type: application/json
{
"kind": "gamesConfiguration#imageConfiguration",
"url": string,
"resourceId": string,
"imageType": string
}
Многочастная загрузка
Если вы хотите отправить метаданные вместе с загружаемыми данными, можно создать один запрос multipart/related. Этот вариант подходит, если объем передаваемых данных достаточно мал, чтобы при сбое соединения можно было загрузить их заново.
Чтобы использовать многочастную загрузку, отправьте запрос POST или PUT к URI /upload метода и добавьте параметр запроса uploadType=multipart. Пример:
POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart
Заголовки HTTP верхнего уровня, которые следует использовать при отправке запроса на многочастную загрузку, включают:
-Content-Type. Установите значение multipart/related и добавьте строку-разделитель, которая используется для идентификации частей запроса.
-Content-Length. Укажите общее количество байтов в теле запроса. Размер медиаконтента в запросе должен быть меньше максимального размера файла, указанного для этого метода.
Тело запроса имеет формат multipart/related (согласно RFC2387) и содержит ровно две части. Части определяются с помощью строки-разделителя, а после последнего разделителя следуют два дефиса.
Каждая часть многокомпонентного запроса должна иметь дополнительный заголовок Content-Type:
Часть с метаданными должна идти первой, а значение Content-Type должно соответствовать одному из поддерживаемых форматов метаданных.
Медиачасть должна идти второй, а Content-Type должен соответствовать одному из поддерживаемых методом MIME-типов медиаконтента.
Список поддерживаемых MIME-типов медиаконтента и ограничений на размер загружаемых файлов для каждого метода приведен в справочнике по Publishing API.
Пример: многокомпонентная загрузка
В примере ниже показан запрос на многочастную загрузку для Publishing API сервисов Play Games.
POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body
--foo_bar_baz
Content-Type: application/json; charset=UTF-8
{
"kind": "gamesConfiguration#imageConfiguration",
"url": string,
"resourceId": string,
"imageType": string
}
--foo_bar_baz
Content-Type: image/png
PNG data
--foo_bar_baz--
Если запрос выполнен успешно, сервер возвращает код статуса HTTP 200 OK вместе с метаданными:
HTTP/1.1 200
Content-Type: application/json
{
"kind": "gamesConfiguration#imageConfiguration",
"url": string,
"resourceId": string,
"imageType": string
}
Возобновляемая загрузка
Чтобы загружать файлы данных более надежно, можно использовать протокол возобновляемой загрузки. Этот протокол позволяет возобновить загрузку после того, как передача данных была прервана из-за сбоя связи. Особенно полезно использовать этот параметр при передаче больших файлов, когда высока вероятность сбоя сети или передачи, например при загрузке из мобильного клиентского приложения. Он также позволяет снизить использование пропускной способности в случае сбоев сети, поскольку вам не придется начинать загрузку больших файлов с самого начала.
Чтобы использовать возобновляемую загрузку, выполните следующие действия:
Начните сеанс с возможностью возобновления. Отправьте начальный запрос на URI загрузки, включив в него метаданные, если они есть.
Сохраните URI сеанса с возможностью возобновления. Сохраните URI сеанса, возвращенный в ответе на первоначальный запрос. Он понадобится вам для остальных запросов в этом сеансе. Читайте подробную статью
Отправьте медиафайл в URI сеанса с возможностью возобновления.
Кроме того, в приложениях, использующих возобновляемую загрузку, должен быть код для возобновления прерванной загрузки. Если загрузка прервалась, узнайте, сколько данных было успешно получено, а затем возобновите загрузку с этого момента.
Как начать сеанс с возможностью возобновления
Чтобы начать возобновляемую загрузку, отправьте запрос POST или PUT на URI /upload метода и добавьте параметр запроса uploadType=resumable. Пример:
POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable
Тело этого запроса пустое или содержит только метаданные. Фактическое содержимое файла, который вы хотите загрузить, будет передано в последующих запросах.
Используйте следующие HTTP-заголовки с исходным запросом:
X-Upload-Content-Type. Укажите MIME-тип медиаконтента, который будет передан в последующих запросах.X-Upload-Content-Length. Укажите количество байтов загружаемых данных, которые будут переданы в последующих запросах. Если длина неизвестна на момент запроса, этот заголовок можно не указывать.Если вы предоставляете метаданные, выполните следующие действия:
Content-Type. Установите значение в соответствии с типом данных метаданных.Content-Length. Укажите количество байтов, предоставленных в теле этого исходного запроса. Необязательный параметр, если вы используете передачу с разделением на фрагменты.
Ознакомьтесь со справочной информацией о Publishing API, чтобы узнать, какие MIME-типы медиаконтента и ограничения на размер загружаемых файлов поддерживаются для каждого метода.
Пример запроса на возобновление сеанса
В примере ниже показано, как запустить сеанс с возможностью возобновления для Play Games Services Publishing API.
POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: image/png
X-Upload-Content-Length: 2000000
{
"kind": "gamesConfiguration#imageConfiguration",
"url": string,
"resourceId": string,
"imageType": string
}
В следующем разделе описано, как обрабатывать ответ.
Сохраните URI возобновляемого сеанса
Если запрос на инициацию сеанса выполнен успешно, сервер API отвечает кодом статуса HTTP 200
OK. Кроме того, он предоставляет заголовок Location, в котором указан URI сеанса с возможностью возобновления. Заголовок Location, показанный в примере ниже, содержит часть параметра запроса upload_id, в которой указан уникальный идентификатор загрузки, используемый для этого сеанса.
Пример ответа на запрос о возобновлении сеанса
Вот ответ на запрос, описанный в шаге 1:
HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0
Значение заголовка Location, как показано в примере ответа выше, – это URI сеанса, который вы будете использовать в качестве конечной точки HTTP для загрузки файла или запроса статуса загрузки.
Скопируйте и сохраните URI сеанса, чтобы использовать его в последующих запросах.
Загрузка видео на YouTube
Чтобы загрузить файл, отправьте запрос PUT на URI для загрузки, полученный на предыдущем шаге. Формат запроса на загрузку:
PUT session_uri
HTTP-заголовки, которые используются при отправке запросов на возобновляемую загрузку файлов, включают:
Content-Length Укажите количество байтов, которые вы загружаете в этом запросе. Обычно это размер загружаемого файла.
Пример запроса на возобновляемую загрузку файла
Ниже приведен пример возобновляемого запроса на загрузку всего PNG-файла размером 2 000 000 байт.
PUT https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/png
bytes 0-1999999
Если запрос выполнен успешно, сервер отвечает объектом HTTP 201 Created и метаданными, связанными с этим ресурсом. Если исходный запрос возобновляемого сеанса был PUT, то для обновления существующего ресурса успешный ответ будет 200 OK вместе с любыми метаданными, связанными с этим ресурсом.
Если запрос на загрузку прерван или вы получили от сервера ответ HTTP 503 Service Unavailable или любой другой ответ 5xx, следуйте инструкциям в разделе Как возобновить прерванную загрузку.
Загрузите файл по частям
При возобновляемой загрузке файл разбивается на фрагменты, и каждый из них загружается в последовательности запросов. Этот подход не рекомендуется, поскольку дополнительные запросы снижают производительность и обычно не нужны. Однако вам может понадобиться использовать разбиение на фрагменты, чтобы уменьшить объем данных, передаваемых в одном запросе. Это полезно, когда для отдельных запросов установлено фиксированное ограничение по времени, как в случае с некоторыми классами запросов Google App Engine. Кроме того, он позволяет, например, показывать индикаторы прогресса загрузки в устаревших браузерах, которые по умолчанию не поддерживают эту функцию.
Если вы загружаете данные по частям, то вместе с заголовком Content-Length, который требуется при загрузке полного файла, необходимо также указать заголовок Content-Range:
Content-Length. Укажите размер фрагмента или меньшее значение, если это последний запрос.Content-Range. Показывает, какие байты файла вы загружаете. Например,Content-Range: bytes 0-524287/2000000означает, что вы предоставляете первые 524 288 байт (256 x 1024 x 2) из файла размером 2 000 000 байт.
Как возобновить прерванную загрузку
Если запрос на загрузку был прерван до получения ответа или если вы получили от сервера ответ HTTP 503 Service Unavailable, вам нужно возобновить прерванную загрузку. Чтобы возобновить прерванную загрузку, выполните следующие действия:
Статус запроса. Чтобы узнать текущий статус загрузки, отправьте пустой запрос
PUTна URI загрузки. В заголовках HTTP-запроса должен быть заголовокContent-Range, указывающий, что текущая позиция в файле неизвестна. Например, если общая длина файла составляет 2 000 000, установите для параметраContent-Rangeзначение*/2000000. Если вы не знаете полный размер файла, задайте для заголовка Content-Range значение*/*.Получение количества загруженных байтов. Обработка ответа на запрос статуса Сервер использует заголовок
Rangeв ответе, чтобы указать, какие байты он уже получил. Например, заголовокRangeсо значением0-299999указывает,что получены первые 300 000 байт файла.Загрузите оставшиеся данные. Теперь, когда вы знаете, с какого места нужно возобновить запрос, отправьте оставшиеся данные или текущий фрагмент. Обратите внимание, что оставшиеся данные в любом случае нужно рассматривать как отдельный фрагмент, поэтому при возобновлении загрузки необходимо отправить заголовок
Content-Range.
Пример: как возобновить прерванную загрузку
Запросите статус загрузки. В следующем запросе заголовок Content-Range используется для того,чтобы указать,что текущая позиция в файле размером 2 000 000 байт неизвестна.
PUT {session_uri} HTTP/1.1 Content-Length: 0 Content-Range: bytes */2000000Извлеките из ответа количество загруженных байтов. В ответе сервера заголовок
Rangeуказывает, что получены первые 43 байта файла. Используйте верхнее значение заголовка Range, чтобы определить, с какого места возобновить загрузку.HTTP/1.1 308 Resume Incomplete Content-Length: 0 Range: 0-42Возобновите загрузку с того места, где она была прервана. В следующем запросе загрузка возобновляется путем отправки оставшихся байтов файла, начиная с байта 43.
PUT {session_uri} HTTP/1.1 Content-Length: 1999957 Content-Range: bytes 43-1999999/2000000 bytes 43-1999999
Обработка ошибок
При загрузке медиаконтента полезно знать некоторые рекомендации по обработке ошибок.
Возобновление или повторная попытка загрузки при сбоях подключения или ошибках 5xx, в том числе:
500 Internal Server Error502 Bad Gateway503 Service Unavailable504 Gateway Timeout
Используйте стратегию экспоненциальной выдержки, если при возобновлении или повторной отправке запросов на загрузку возвращается ошибка сервера
5xx. Эти ошибки могут возникать, если сервер перегружен. Экспоненциальное увеличение интервала между повторными попытками помогает снизить нагрузку на сеть при большом количестве запросов или интенсивном трафике.Другие типы запросов не должны обрабатываться с экспоненциальной выдержкой, но вы можете повторить некоторые из них. При повторной отправке таких запросов ограничьте количество попыток. Например, ваш код может ограничивать количество попыток до десяти или меньше, прежде чем сообщить об ошибке.
При возобновляемой загрузке обрабатывайте ошибки
404 Not Foundи410 Gone, начиная загрузку с самого начала.
Экспоненциальная выдержка
Экспоненциальная выдержка – это стандартная стратегия обработки ошибок для сетевых приложений, в которой клиент периодически повторяет неудачный запрос с увеличивающимися интервалами. Если сервер возвращает ошибки из-за большого количества запросов или интенсивного сетевого трафика, для обработки этих ошибок может подойти экспоненциальное откладывание. В то же время она не подходит для устранения ошибок, не связанных с объемом трафика или временем ответа, например недопустимых учетных данных для авторизации или ошибок "Файл не найден".
При правильном использовании экспоненциальная выдержка повышает эффективность использования пропускной способности, уменьшает количество запросов, необходимых для получения успешного ответа, и увеличивает производительность запросов в параллельных средах.
Вот как реализовать простую экспоненциальную выдержку:
- Отправьте запрос к API.
- Получить ответ
HTTP 503, который означает, что нужно повторить запрос. - Подождите 1 секунду + random_number_milliseconds и повторите запрос.
- Получить ответ
HTTP 503, который означает, что нужно повторить запрос. - Подождите 2 секунды + random_number_milliseconds и повторите запрос.
- Получить ответ
HTTP 503, который означает, что нужно повторить запрос. - Подождите 4 секунды + случайное количество миллисекунд и повторите запрос.
- Получить код
HTTP 503 response, который означает, что нужно повторить запрос. - Подождите 8 секунд + случайное количество миллисекунд и повторите запрос.
- Получить код
HTTP 503 response, который означает, что нужно повторить запрос. - Подождите 16 секунд + random_number_milliseconds и повторите запрос.
- Останови. Сообщить об ошибке или зарегистрировать ее.
В приведенном выше списке random_number_milliseconds – это случайное число миллисекунд, не превышающее 1000. Это необходимо, поскольку небольшая случайная задержка помогает более равномерно распределить нагрузку и избежать перегрузки сервера. Значение random_number_milliseconds необходимо переопределять после каждого ожидания.
Алгоритм настроен на завершение, когда n равно 5. Это ограничение не позволяет клиентам бесконечно повторять попытки и приводит к общей задержке примерно в 32 секунды, после чего запрос считается "неустранимой ошибкой". Увеличить максимальное количество попыток можно, особенно если выполняется длительная загрузка. Однако задержку между попытками следует ограничить разумным значением, например менее одной минуты.