Graph API

API Resumable Upload

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

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

Ссылки для конечных точек, которые поддерживают дескрипторы загруженных файлов, укажут, поддерживают ли конечные точки дескрипторы, возвращаемые API Resumable Upload.

Загрузка файлов

Загрузка файла выполняется за два шага:

  1. Используйте конечную точку Application Uploads, чтобы описать свой файл и создать сеанс загрузки.
  2. Используйте возвращенный ID сеанса загрузки, чтобы начать сеанс загрузки.

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

Шаг 1. Создайте сеанс.

Отправьте запрос POST, описывающий ваш файл, к конечной точке Application Uploads ({app-id}/uploads). В случае успеха будет получен ID сеанса, который можно использовать в следующем шаге для начала загрузки.

Синтаксис запроса

POST https://graph.facebook.com/{api-version}/{app-id}/uploads
  &file_length={file-length}
  &file_type={file-type}
  &access_token={access-token}

Заполнители параметров:

  • {api-version} — версия API Graph.
  • {app-id} — ID приложения. Загруженный файл будет связан с этим приложением. Пользователь приложения должен иметь роль администратора или разработчика для этого приложения.
  • file-length — размер файла (в байтах).
  • file-type — тип MIME файла. Допустимые значения: application/pdf, image/jpeg, image/jpg, image/png и video/mp4.
  • {access-token} — маркер доступа пользователя приложения.

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

Ответ

{
  "id": "{id}"
}

Значения свойств ответа:

  • {id} — ID сеанса загрузки.

Пример запроса

curl -X POST \
 "https://graph.facebook.com/v19.0/584544743160774/uploads?file_length=109981&file_type=image/png&access_token=EAAIT..."

Пример ответа

{
    "id": "upload:MTphd..."
}

Шаг 2. Начните загрузку.

Начните сеанс загрузки, для чего отправьте запрос POST на адрес узла API Graph и добавьте {id} своего сеанса загрузки вместе с необходимыми заголовками, приведенными ниже. В случае успеха будет получен дескриптор файла, а именно {h}, который затем можно использовать с любыми конечными точками API Graph, поддерживающими дескрипторы файлов, которые возвращаются API Resumable Upload.

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

Синтаксис запроса

POST https://graph.facebook.com/{api-version}/{upload-session-id}
  --header 'Authorization: OAuth {access-token}' 
  --header 'file_offset: 0'
  --data-binary @{file-name}

Значения заполнителей

  • {api-version} — версия API Graph.
  • {upload-session-id} — ID сеанса загрузки, полученный в шаге 1.
  • {access-token} — маркер доступа пользователя приложения. У пользователя приложения должна быть роль в приложении, которое было задействовано в шаге 1.
  • {file-name} — имя загружаемого файла.

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

Ответ

{
  "h": "{h}"
}

Значения свойств ответа:

  • {h} — дескриптор файла загружаемого файла.

Пример запроса

curl -X POST \
 "https://graph.facebook.com/v19.0/upload:MTphd..." \
 --header "Authorization: OAuth EAAIT..." \
 --header "file_offset: 0" \
 --data-binary @cats_are_jerks.png

Пример ответа

{
    "h": "2:c2FtcGxl..."
}

Прерывания

Если начатый вами сеанс загрузки выполняется дольше, чем ожидалось, или был прерван, отправьте запрос GET на адрес узла API Graph и добавьте ID сеанса загрузки. API вернет значение file_offset, которое можно использовать для возобновления сеанса загрузки с того момента, когда он был прерван.

Синтаксис запроса

GET https://graph.facebook.com/{api-version}/{upload-session-id}
  ?access_token={access-token}

Значения заполнителей:

  • {api-version} — версия API Graph.
  • {upload-session-id} — ID сеанса загрузки, полученный в разделе Шаг 1. Создайте сеанс.
  • {access-token} — маркер доступа пользователя приложения.

Ответ

{
  "id": "{id}",
  "file_offset": {file-offset}
}

Значения свойств ответа:

  • {id} — ID сеанса загрузки, который был запрошен.
  • {file-offset} — целое значение, обозначающее количество успешно загруженных байтов.

Используйте значение file_offset и повторите действия из раздела Шаг 2. Начните загрузку, присвоив это значение соответствующему заголовку file_offset. Это позволит возобновить загрузку с момента ее прерывания.

Пример запроса

curl -X GET \
 "https://graph.facebook.com/v19.0/upload:MTphd...&access_token=EAAIT..." \

Пример ответа

{
  "id": "upload:MTphd",
  "file_offset": 5238
}