API Video

Primi passi

Questo tutorial mostra come utilizzare l'API Video per creare un video su una Pagina. Presuppone che tu sappia come eseguire richieste cURL di base con uno strumento da riga di comando come Terminal oppure con un'app come Postman e che abbia sufficiente familiarità con il Tool di esplorazione per la API Graph.

Prima di iniziare

Ecco cosa ti servirà:

  • Un'app Facebook già esistente. Se non ne hai una, accedi a Facebook for Developers, clicca su Le mie app e creane una.
  • Un video di 10-20 MB che hai suddiviso in porzioni da 5 MB, con tutte le porzioni in una singola directory.
  • Una Pagina su cui sei in grado di eseguire attivitàCREATE_CONTENT.
  • Accesso a uno strumento da riga di comando (come Terminal) o a un'app (come Postman) in grado di eseguire richieste cURL.

Passaggio 1: acquisizione di un token d'accesso dell'utente

Come pratica generale, devi implementare Facebook Login nella tua app e usarlo per ottenere token d'accesso dagli utenti della tua app. Tuttavia, per questo tutorial, puoi utilizzare il Tool di esplorazione per la API Graph poiché ha già Facebook Login implementato, il che ti consente di generare facilmente token per qualsiasi tua app.

  1. Carica il Tool di esplorazione per la API Graph e dal menu a discesa dell'app Facebook seleziona la tua app.

  2. Nel menu a discesa Utente o Pagina, seleziona Ricevi token d'accesso dell'utente e autenticati. Se stai riutilizzando un'app meno recente, potresti essere già autenticato.

  3. Nella sezione Autorizzazioni, usa il campo di ricerca Aggiungi un'autorizzazione per cercare e selezionare le seguenti autorizzazioni: pages_manage_engagement e pages_read_user_content.
  4. Clicca su Genera token d'accesso.
  5. Nella finestra modale che appare, autenticati e scegli la Pagina in cui vuoi caricare il video.
  6. Clicca su Avanti per il resto delle schermate fino a quando non si chiude la finestra modale. In questo modo la tua app ottiene le autorizzazioni che hai selezionato e genera anche un token d'accesso dell'utente.
  7. Facoltativo. Clicca sull'icona blu delle informazioni per verificare di aver concesso alla tua app le autorizzazioni corrette (ambiti).

Passaggio 2: acquisizione dell'ID della tua Pagina e del relativo token

  1. Utilizzando il Tool di esplorazione per la API Graph, invia una richiesta al segmento GET /me/accounts. Questo interroga il tuo utente e restituisce tutte le Pagine per cui hai autorizzato la tua app ad accedere nell'ultimo passaggio.
  2. Identifica la tua Pagina nella risposta e copia il suo ID (id) e il token d'accesso della Pagina (access_token).
    3. {
  "data": [
    {
      "access_token": "EBACf...",  //Copy your Page Access Token
      "category": "Media",
      "category_list": [
        {
          "id": "163003840417682",
          "name": "Media"
        }
      ],
      "name": "Metricsaurus",
      "id": "1755847768034402",  //Copy your Page ID
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "MTc1NTg0Nzc2ODAzNDQwMgZDZD",
      "after": "MTc1NTg0Nzc2ODAzNDQwMgZDZD"
    }
  }
}

Passaggio 3: creazione di una sessione video

  1. Nello strumento da riga di comando, vai alla cartella contenente le porzioni del tuo video, quindi invia una richiesta cURL al segmento POST /page-id/videos sull'host graph-video.facebook.com. Se utilizzi Postman, includi le chiavi e i valori dei parametri di query nella richiesta Corpo come form-data.

    2. Esempio di richiesta
    curl -X POST \
  "https://graph-video.facebook.com/1755847768034402/videos" \
  -F "access_token=EBACf..." \
  -F "upload_phase=start" \
  -F "file_size=77188035"
  2. Sostituisci l'ID Pagina (1755847768034402) nel percorso della richiesta con l'ID della tua Pagina, imposta access_token sul token d'accesso della Pagina appena copiato e file_size sulla dimensione totale del file video, in byte.

    3. L'API restituisce una sessione video: 
    {
  "video_id": "225467151853466",
  "start_offset": "0",
  "end_offset": "1048576",
  "upload_session_id": "225467155186799"
}
  3. Copia tutti i valori restituiti, ad eccezione di end_offset.

Passaggio 4: caricamento della prima porzione di video

Invia un'altra richiesta al segmento POST /{page-id}/videos e includi il tuo upload_session_id e il nome della prima porzione del video.

Esempio di richiesta

curl -X POST \
  "https://graph-video.facebook.com/1755847768034402/videos" \
  -F "access_token=EBACf..." \
  -F "upload_phase=transfer" \
  -F "start_offset=0" \
  -F "upload_session_id=225467155186799" \
  -F "video_file_chunk=@xaa"

Se utilizzi cURL, includi il simbolo @ prima del nome del file.

Se utilizzi Postman, ometti il simbolo @, imposta video_file_chunk su File (passa il mouse sulla riga per attivare il menu a discesa) e seleziona manualmente il file della prima porzione.

L'API risponderà con un nuovo start_offset. Acquisisci il nuovo valore.

{
  "start_offset": "10485760",
  "end_offset": "15728640"
}

Passaggio 5: caricamento delle porzioni di video rimanenti

  1. Esegui la stessa richiesta, ma imposta start_offset sul nuovo valore start_offset restituito nella risposta precedente e imposta video_file_chunk sul nome della successiva porzione di video della sequenza.
    2. curl -X POST \
  "https://graph-video.facebook.com/1755847768034402/videos" \
  -F "access_token=EBACf..." \
  -F "upload_phase=transfer" \
  -F "start_offset=10485760" \
  -F "upload_session_id=225467155186799" \
  -F "video_file_chunk=@xab"
    L'API risponderà ancora una volta con un nuovo valore start_offset, che puoi utilizzare per caricare la successiva porzione della sequenza. 
    {
  "start_offset":"15728640",
  "end_offset":"20971520"
}
  2. Continua a ripetere questo passaggio fino a caricare tutte le porzioni di video rimanenti nell'ordine corretto. Il programma utilizzato per suddividere il file video in porzioni deve essere in grado di denominare le porzioni in ordine sequenziale.

Passaggio 6: conclusione della sessione di caricamento

Dopo aver caricato l'ultima porzione, termina la sessione di caricamento inviando una richiesta finale allo stesso endpoint e imposta upload_phase su fine.

Esempio di richiesta

curl -X POST \
  "https://graph-video.facebook.com/1755847768034402/videos"  \
  -F "access_token=EBACf..." \
  -F "upload_phase=finish" \
  -F "upload_session_id=225467155186799"

In caso di azione eseguita correttamente, l'API terminerà la sessione di caricamento e risponderà con true.

{
  "success": true
}

Procederemo ora ad assemblare e codificare il tuo video. Il processo di codifica può richiedere alcuni minuti per essere completato, a seconda delle dimensioni totali del file video.