API Graph

API de subida reanudable

La API de subida reanudable te permite subir archivos grandes a la API Graph y reanudar las sesiones de subida interrumpidas sin tener que empezar de nuevo. Una vez subidos, puedes usar el identificador de un archivo subido con otros puntos de conexión de la API Graph que los admitan.

Ten en cuenta que la API de subida reanudable no es la única manera de subir archivos. Muchos nodos tienen un perímetro que admite la subida, pero la mayoría no tiene manera de manejar archivos grandes o de reanudar una sesión de subida interrumpida.

Las referencias a los puntos de conexión que admiten los identificadores de archivos subidos indicarán si los puntos de conexión son compatibles con los identificadores que devuelve la API de subida reanudable.

Pasos para la subida

Subir un archivo es un proceso de dos pasos:

  1. Utiliza el punto final Subidas de apps para describir tu archivo y crear una sesión de subida.
  2. Usa el identificador de la sesión de subida que se devolvió para iniciar el proceso de subida.

Si se realiza de manera correcta, se devolverá un identificador de archivo que se puede usar con otros puntos de conexión que admiten identificadores de archivo que devolvió la API de subida reanudable.

Paso 1: Crear una sesión

Envía una solicitud POST que describa el archivo en el punto de conexión de las Subidas de apps ({app-id}/uploads). Si la operación se realiza correctamente, se devolverá un identificador de sesión de subida, que puedes usar en el próximo 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}: la versión de la API Graph.
  • {app-id}: el identificador de la app. El archivo subido que se asociará con esta app. El usuario de la app debe tener un rol de administrador o de desarrollador en esta app.
  • file-length: el tamaño del archivo en bytes.
  • file-type: el tipo MIME del archivo. Los valores válidos son: application/pdf, image/jpeg, image/jpg, image/png y video/mp4
  • {access-token}: el token de acceso de usuario del usuario de la app.

Consulta la referencia del punto de conexión Subidas de apps para obtener una lista completa de parámetros de consulta disponibles y de los tipos de archivos admitidos.

Respuesta

{
  "id": "{id}"
}

Valores de la propiedad de respuesta:

  • {id}: el identificador de 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

Inicia la sesión de subida enviando una solicitud POST a la dirección del host de la API Graph, y agrega el {id} de la sesión de subida junto con los encabezados obligatorios que se indican a continuación. Si se realiza de manera correcta, se devolverá un identificador de archivo {h}, que puedes usar con los puntos de conexión de la API Graph que admiten identificadores de archivo que devolvió la API de subida reanudable.

Si la sesión de subida toma más tiempo del que se espera o si se interrumpió, 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}: la versión de la API Graph.
  • {upload-session-id}: el identificador de sesión de subida que se devolvió en el paso 1.
  • {access-token}: el token de acceso de usuario del usuario de la app. El usuario de la app debe tener un rol en la app a la que se hace referencia en el paso 1.
  • {file-name}: nombre del archivo que se subirá.

Debes incluir el token de acceso en el encabezado; caso contrario, se producirá un error en la solicitud.

Respuesta

{
  "h": "{h}"
}

Valores de la propiedad de respuesta:

  • {h}: el identificador del archivo 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 iniciaste una sesión de subida, pero toma más tiempo del que se espera o si se interrumpió, envía una solicitud GET a la dirección del host de la API Graph y agrega el identificador de la sesión de subida. La API devuelve un valor file_offset, que puedes usar para reanudar el proceso de subida desde donde se interrumpió.

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}: la versión de la API Graph.
  • {upload-session-id}: el identificador de la sesión de subida que se devuelve en Paso 1: Crear una sesión.
  • {access-token}: el token de acceso de usuario del usuario de la app.

Respuesta

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

Valores de la propiedad de respuesta:

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

Captura el valor file_offset y repite el Paso 2: Iniciar la subida, lo que permitirá asignar el valor al encabezado file_offset correspondiente. Esto reanudará el proceso de subida desde donde se interrumpió.

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
}