API Graph

API Resumable Upload

L'API Resumable Upload consente il caricamento di file di grandi dimensioni nell'API Graph e la ripresa delle sessioni di caricamento interrotte senza dover ricominciare. Dopo il caricamento, puoi usare l'handle di un file caricato con altri endpoint dell'API Graph che li supportano.

Tieni presente che l'API Resumable Upload non rappresenta l'unico modo per caricare file. Molti nodi hanno un segmento che supporta il caricamento, ma la maggior parte non consente di gestire file di grandi dimensioni o riprendere una sessione di caricamento interrotta.

I riferimenti per gli endpoint che supportano gli handle dei file caricati indicheranno se tali endpoint supportano gli handle restituiti dall'API Resumable Upload.

Passaggi di caricamento

Il caricamento di un file è una procedura a due passaggi:

  1. Utilizza l'endpoint Application Uploads per descrivere il file e creare una sessione di caricamento.
  2. Utilizza l'ID della sessione di caricamento restituito per avviare la procedura di caricamento.

Se l'azione è stata eseguita correttamente, verrà restituito un handle di file che potrai usare con altri endpoint che supportano gli handle di file restituiti dall'API Resumable Upload.

Passaggio 1: creazione di una sessione

Invia una richiesta POST che descriva il file all'endpoint Application Uploads ({app-id}/uploads). In caso di azione eseguita correttamente, viene restituito un ID della sessione di caricamento che puoi utilizzare nel passaggio successivo per avviare il caricamento.

Sintassi della richiesta

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

Segnaposto dei parametri:

  • {api-version}: la versione dell'API Graph.
  • {app-id}: l'ID app. Il file caricato che sarà associato a questa app. L'utente dell'app deve avere un ruolo di amministratore o sviluppatore in questa app.
  • file-length: le dimensioni del file, in byte.
  • file-type: il tipo MIME del file. I valori validi sono: application/pdf, image/jpeg, image/jpg, image/png e video/mp4
  • {access-token}: il token d'accesso utente dell'utente dell'app.

Consulta il riferimento per l'endpoint Application Uploads per una lista completa dei parametri delle query disponibili e dei tipi di file supportati.

Risposta

{
  "id": "{id}"
}

Valori della proprietà della risposta:

  • {id}: ID della sessione di caricamento.

Esempio di richiesta

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

Esempio di risposta

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

Passaggio 2: avvio del caricamento

Avvia la sessione di caricamento inviando una richiesta POST all'indirizzo host dell'API Graph e aggiungi {id} della sessione di caricamento insieme alle intestazioni richieste indicate di seguito. In caso di azione eseguita correttamente, viene restituito un handle di file, {h}, che puoi usare con altri endpoint dell'API Graph che supportano gli handle di file restituiti dall'API Resumable Upload.

Se la sessione di caricamento richiede più tempo del previsto o è stata interrotta, segui i passaggi descritti nella sezione Interruzioni.

Sintassi della richiesta

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

Valori dei segnaposto

  • {api-version}: versione dell'API Graph.
  • {upload-session-id}: l'ID della sessione di caricamento restituito durante il passaggio 1.
  • {access-token}: token d'accesso utente dell'utente dell'app. L'utente dell'app deve avere un ruolo nell'app che è stata targetizzata al passaggio 1.
  • {file-name}: il nome del file da caricare.

Devi includere il token d'accesso nell'intestazione o la tua richiesta non andrà a buon fine.

Risposta

{
  "h": "{h}"
}

Valori della proprietà della risposta:

  • {h}: l'handle del file caricato

Esempio di richiesta

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

Esempio di risposta

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

Interruzioni

Se hai avviato una sessione di caricamento, ma questa sta richiedendo più tempo del previsto o è stata interrotta, invia una richiesta GET all'indirizzo host dell'API Graph e aggiungi l'ID della sessione di caricamento. L'API restituisce un valore file_offset che puoi usare per riprendere la procedura di caricamento dal punto in cui è stata interrotta.

Sintassi della richiesta

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

Valori dei segnaposto:

  • {api-version}: versione dell'API Graph.
  • {upload-session-id}: ID della sessione di caricamento restituito durante il Passaggio 1: creazione di una sessione.
  • {access-token}: token d'accesso utente dell'utente dell'app.

Risposta

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

Valori della proprietà della risposta:

  • {id}: ID della sessione di caricamento richiesto.
  • {file-offset}: un numero intero che indica il numero di byte caricati correttamente.

Acquisisci il valore file_offset e ripeti il Passaggio 2: avvio del caricamento, assegnando il valore all'intestazione file_offset corrispondente. In questo modo, la procedura di caricamento riparte dal punto in cui è stata interrotta.

Esempio di richiesta

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

Esempio di risposta

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