API Graph

API Upload avec reprise

L’API Upload avec reprise vous permet d’importer des fichiers volumineux dans l’API Graph et de reprendre les sessions d’importation interrompues sans avoir à tout recommencer. Une fois un fichier importé, vous pouvez utiliser son alias avec les autres points de terminaison de l’API Graph qui les acceptent.

Veuillez noter que l’API Upload avec reprise n’est pas le seul moyen d’importer des fichiers. De nombreux nœuds ont une arête qui autorise l’importation, mais la plupart ne permettent pas de gérer des fichiers volumineux ou de reprendre une session d’importation interrompue.

Les références des points de terminaison qui autorisent les alias de fichiers importés indiquent si ces points de terminaison acceptent les alias renvoyés par l’API Upload avec reprise.

Étapes d’importation

L’importation d’un fichier est un processus en deux étapes :

  1. Utilisez le point de terminaison d’importations d’application pour décrire votre fichier et créer une session d’importation.
  2. Utilisez l’ID de session d’importation renvoyé pour lancer le processus d’importation.

Si le processus aboutit, un alias de fichier sera renvoyé que vous pourrez alors utiliser avec d’autres points de terminaison acceptant les alias de fichier renvoyés par l’API Upload avec reprise.

Étape 1 : Créer une session

Envoyez une requête POST qui décrit votre fichier au point de terminaison d’importations d’application ({app-id}/uploads). Si le processus aboutit, un ID de session d’importation sera renvoyé que vous pourrez alors utiliser à l’étape suivante pour lancer l’importation.

Syntaxe de la requête

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

Espaces réservés aux paramètres :

  • {api-version} : version de l’API Graph.
  • {app-id} : ID de l’application. Le fichier importé qui sera associé à cette application. L’utilisateur·ice de l’application doit avoir dans celle-ci un rôle d’administration ou de développement.
  • file-length : taille du fichier en octets.
  • file-type : type MIME du fichier. Les valeurs valides sont les suivantes : application/pdf, image/jpeg, image/jpg, image/png et video/mp4
  • {access-token} : token d’accès utilisateur de l’utilisateur·ice de l’application.

Consultez la référence du point de terminaison d’importations d’application pour une liste complète des paramètres de requête disponibles et des types de fichiers pris en charge.

Réponse

{
  "id": "{id}"
}

Valeurs de la propriété de réponse :

  • {id} : ID de la session d’importation.

Exemple de requête

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

Exemple de réponse

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

Étape 2 : Lancer l’importation

Lancez la session d’importation en envoyant une requête POST à l’adresse de l’hôte de l’API Graph, puis ajoutez l’{id} de votre session d’importation avec les en-têtes requis indiqués ci-dessous. Lorsque le processus aboutit, un alias de fichier, {h}, est renvoyé que vous pouvez alors utiliser avec n’importe quel point de terminaison d’API Graph qui accepte les alias de fichiers renvoyés par l’API Upload avec reprise.

Si les sessions d’importation prennent plus de temps que prévu ou ont été interrompues, suivez les étapes décrites dans la section Interruptions.

Syntaxe de la requête

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

Valeurs des espaces réservés

  • {api-version} : version de l’API Graph.
  • {upload-session-id} : ID de session d’importation renvoyé à l’Étape 1.
  • {access-token} : token d’accès utilisateur de l’utilisateur·ice de l’application. L’utilisateur·ice doit jouer un rôle dans l’application ciblée à l’Étape 1.
  • {file-name} : nom du fichier à importer.

Vous devez inclure le token d’accès dans l’en-tête, sinon votre requête échouera.

Réponse

{
  "h": "{h}"
}

Valeurs de la propriété de réponse :

  • {h} : alias du fichier importé

Exemple de requête

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

Exemple de réponse

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

Interruptions

Si vous avez lancé une session d’importation, mais qu’elle prend plus de temps que prévu ou qu’elle a été interrompue, envoyez une requête GET à l’adresse de l’hôte de l’API Graph et ajoutez l’ID de votre session d’importation. L’API renvoie une valeur file_offset que vous pouvez utiliser pour reprendre le processus d’importation à partir du point d’interruption.

Syntaxe de la requête

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

Valeurs des espaces réservés :

  • {api-version} : version de l’API Graph.
  • {upload-session-id} : ID de la session d’importation renvoyé à l’Étape 1 : Créer une session.
  • {access-token} : token d’accès utilisateur de l’utilisateur·ice de l’application.

Réponse

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

Valeurs de la propriété de réponse :

  • {id} : ID de la session d’importation sur laquelle a porté la requête.
  • {file-offset} : nombre entier indiquant le nombre d’octets qui ont bien été importés.

Capturez la valeur file_offset et répétez l’Étape 2 : Lancer l’importation, en assignant cette valeur à l’en-tête file_offset correspondant. Cela permettra de reprendre le processus d’importation à partir du point d’interruption.

Exemple de requête

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

Exemple de réponse

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