Graph API

Resumable Upload API

Über die Resumable Upload API kannst du große Dateien in die Graph API hochladen und unterbrochene Upload-Sitzungen fortsetzen, ohne dass du sie erneut von Beginn starten musst. Nach den Hochladen kannst du den Handle einer hochgeladenen Datei mit anderen Endpunkten der Graph API verwenden, die ihn unterstützen.

Beachte, dass die Resumable Upload API nicht die einzige Möglichkeit darstellt, Dateien hochzuladen. Viele Nodes verfügen über eine Edge, die das Hochladen unterstützt. Jedoch bieten die meisten keine Möglichkeit für die Verarbeitung großer Dateien oder das Fortsetzen einer unterbrochenen Upload-Sitzung.

Referenzen zu Endpunkten, die Handles hochgeladener Dateien unterstützen, zeigen an, ob Endpunkte Handles unterstützen, die von der Resumable Upload API zurückgegeben wurden.

Schritte für das Hochladen

Zum Hochladen von Dateien sind zwei Schritte erforderlich:

  1. Verwende den Application Uploads-Endpunkt, um deine Datei zu beschreiben und eine Upload-Sitzung zu erstellen.
  2. Verwende die zurückgegebene ID der Upload-Sitzung, um den Upload-Prozess zu starten.

Bei Erfolg wird ein Datei-Handle zurückgegeben, den du dann mit anderen Endpunkten verwenden kannst, die von der Resumable Upload API zurückgegebene Datei-Handle unterstützen.

Schritt 1: Sitzung erstellen

Sende eine POST-Anfrage an den Application Uploads-Endpunkt ({app-id}/uploads), die deine Datei beschreibt. Bei Erfolg wird eine Upload-Sitzungs-ID zurückgegeben, die du im nächsten Schritt verwenden kannst, um das Hochladen zu beginnen.

Anfragesyntax

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

Parameterplatzhalter:

  • {api-version} – Die Graph API-Version.
  • {app-id} – Die App-ID. Die hochgeladene Datei, die mit dieser App verknüpft wird. Der*die App-Nutzer*in muss über eine Administrations- oder Entwicklungsrolle in dieser App verfügen.
  • file-length – Die Dateigröße in Bytes.
  • file-type – Der MIME-Typ der Datei. Gültige Werte: application/pdf, image/jpeg, image/jpg, image/png und video/mp4
  • {access-token} – Der Nutzer*innen-Zugriffsschlüssel des*der App-Nutzer*in.

Eine vollständige Liste der verfügbaren Abfrageparameter und unterstützten Dateitypen findest du in der Referenz zum Application Uploads-Endpunkt.

Antwort

{
  "id": "{id}"
}

Eigenschaftswerte der Antwort:

  • {id} – Upload-Sitzungs-ID.

Beispielanfrage

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

Beispielantwort

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

Schritt 2: Upload beginnen

Starte die Upload-Sitzung, indem du eine POST-Anfrage an die Host-Adresse der Graph API sendest. Hänge dabei die {id} deiner Upload-Sitzung zusammen mit den unten angegebenen erforderlichen Header an. Bei Erfolg wird ein Datei-Handle, {h}, zurückgegeben, den du dann mit jedem Endpunkt der Graph API verwenden kannst, der von der Resumable Upload API zurückgegebene Datei-Handle unterstützt.

Wenn die Upload-Sitzung länger dauert als erwartet oder unterbrochen wurde, befolge die Schritte, die im Abschnitt Unterbrechungen beschrieben sind.

Anfragesyntax

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

Platzhalterwerte

  • {api-version} – Die Graph API-Version.
  • {upload-session-id} – Die in Schritt 1 zurückgegebene ID der Upload-Sitzung.
  • {access-token} – Der Nutzer*innen-Zugriffsschlüssel des*der App-Nutzer*in. Der*die App-Nutzer*in muss über eine Rolle in der App verfügen, die in Schritt 1 anvisiert wurde.
  • {file-name} – Der Name der hochzuladenden Datei.

Beziehe unbedingt den Zugriffsschlüssel in den Header ein, ansonsten wird deine Anfrage fehlschlagen.

Antwort

{
  "h": "{h}"
}

Eigenschaftswerte der Antwort:

  • {h} – Der Datei-Handle der hochgeladenen Datei.

Beispielanfrage

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

Beispielantwort

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

Unterbrechungen

Wenn du eine Upload-Sitzung gestartet hast, diese jedoch mehr Zeit beansprucht als erwartet oder unterbrochen wurde, sende eine GET-Anfrage an die Host-Adresse der Graph API. Hänge dabei die ID deine Upload-Sitzung an. Die API gibt einen file_offset-Wert zurück, den du verwenden kannst, um den Upload-Vorgang dort fortzusetzen, wo er unterbrochen wurde.

Anfragesyntax

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

Platzhalterwerte:

  • {api-version} – Die Graph API-Version.
  • {upload-session-id} – Die in Schritt 1: Sitzung erstellen zurückgegebene ID der Upload-Sitzung.
  • {access-token} – Der Nutzer*innen-Zugriffsschlüssel des*der App-Nutzer*in.

Antwort

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

Eigenschaftswerte der Antwort:

  • {id} – Die Upload-Sitzungs-ID, die abgefragt wurde.
  • {file-offset} – Eine Ganzzahl, die angibt, wie viele Bytes erfolgreich hochgeladen wurden.

Erfasse den file_offset-Wert und wiederhole Schritt 2: Upload beginnen. Weise den Wert dabei dem entsprechenden file_offset-Header zu. Hierdurch wird der Upload-Vorgang dort fortgesetzt, wo er unterbrochen wurde.

Beispielanfrage

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

Beispielantwort

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