API Graph

API de subida reanudable

La API de subida reanudable te permite subir archivos grandes a la API Graph y reanudar sesiones de subida interrumpidas sin tener que volver a empezar. Una vez subido un archivo, puedes usar su identificador con otros extremos de la API Graph que los admitan.

Ten en cuenta que la API de subida reanudable no es la única forma de subir archivos. Muchos nodos tienen un perímetro que admite las subidas, pero la mayoría no disponen de una forma de gestionar archivos grandes ni de reanudar una sesión de subida interrumpida.

En las referencias de los extremos que son compatibles con los identificadores de archivos subidos se indicará si los extremos admiten los identificadores que devuelve la API de subida reanudable.

Pasos para la subida

Para subir un archivo, debes seguir dos pasos:

  1. Usa el extremo de subidas a la aplicación para describir el archivo y crear una sesión de subida.
  2. Usa el identificador de sesión de subida devuelto para iniciar el proceso de subida.

Si la operación se realiza correctamente, se devolverá un identificador de archivo que puedes usar con otros extremos que sean compatibles con los identificadores de archivos que devuelve la API de subida reanudable.

Paso 1: Crear una sesión

Envía una solicitud POST que describa el archivo al extremo de subidas a la aplicación ({app-id}/uploads). Cuando esta operación se lleva a cabo correctamente, se devolverá un identificador de sesión de subida que puedes usar en el siguiente paso para iniciar la subida.

Sintaxis de la solicitud

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

Marcadores de posición de los parámetros:

  • {api-version}: versión de la API Graph.
  • {app-id}: identificador de la aplicación. El archivo subido que se asociará con esta aplicación. El usuario de la aplicación debe tener un rol de administrador o desarrollador en la aplicación.
  • file-length: tamaño del archivo en bytes.
  • file-type: tipo MIME del archivo. Los valores válidos son application/pdf, image/jpeg, image/jpg, image/png y video/mp4.
  • {access-token}: identificador de acceso del usuario de la aplicación.

Consulta la referencia del extremo de subidas a la aplicación para obtener una lista completa de los parámetros de consulta disponibles y los tipos de archivo compatibles.

Respuesta

{
  "id": "{id}"
}

Valores de la propiedad de la respuesta:

  • {id}: identificador de la sesión de subida.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Paso 2: Iniciar la subida

Para iniciar la sesión de subida, envía una solicitud POST a la dirección del host de la API Graph y anexa el {id} de la sesión de subida junto con los encabezados obligatorios que se indican a continuación. Si la operación se realiza correctamente, se devolverá un identificador de archivo ({h}) que puedes usar con cualquier extremo de la API Graph que admita identificadores de archivo devueltos por la API de subida reanudable.

Si la sesión de subida tarda más de lo esperado o se ha interrumpido, sigue los pasos que se describen en la sección Interrupciones.

Sintaxis de la solicitud

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

Valores de los marcadores de posición

  • {api-version}: versión de la API Graph.
  • {upload-session-id}: identificador de la sesión de subida devuelto en el paso 1.
  • {access-token}: identificador de acceso del usuario de la aplicación. El usuario de la aplicación debe tener un rol en la aplicación de destino del paso 1.
  • {file-name}: nombre del archivo que se va a subir.

Debes incluir el identificador de acceso en el encabezado; de lo contrario, la solicitud no se ejecutará correctamente.

Respuesta

{
  "h": "{h}"
}

Valores de la propiedad de la respuesta:

  • {h}: identificador del archivo subido.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Interrupciones

Si has iniciado una sesión de subida, pero está tardando más de lo esperado o se ha interrumpido, envía una solicitud GET a la dirección del host de la API Graph y anexa el identificador de la sesión de subida. La API devuelve un valor de file_offset que puedes usar para reanudar el proceso de subida desde el momento de la interrupción.

Sintaxis de la solicitud

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

Valores de los marcadores de posición:

  • {api-version}: versión de la API Graph.
  • {upload-session-id}: identificador de la sesión de subida que se devolvió en el Paso 1: Crear una sesión.
  • {access-token}: identificador de acceso del usuario de la aplicación.

Respuesta

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

Valores de la propiedad de la respuesta:

  • {id}: identificador de la sesión de subida que se consultó.
  • {file-offset}: entero que indica el número de bytes que se han subido correctamente.

Captura el valor de file_offset y repite el Paso 2: Iniciar la subida; para ello, asigna el valor al encabezado file_offset correspondiente. De esta forma, se reanudará el proceso de subida desde el momento de la interrupción.

Ejemplo de solicitud

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

Ejemplo de respuesta

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