Carica contenuti multimediali

Il caricamento degli elementi multimediali è un processo in due passaggi:

  1. Carica i byte dei tuoi file multimediali su un server di Google tramite l'endpoint per i caricamenti. Viene restituito un token di caricamento che identifica i byte caricati.
  2. Utilizza una chiamata batchCreate con il token di caricamento per creare un elemento multimediale nell'account Google Foto dell'utente.

Questi passaggi descrivono la procedura di caricamento di un singolo elemento multimediale. Se stai caricando più elementi multimediali (molto probabilmente per qualsiasi applicazione di produzione), consulta le best practice per i caricamenti per migliorare l'efficienza del caricamento.

Prima di iniziare

Ambiti di autorizzazione richiesti

Il caricamento di elementi multimediali nella raccolta o nell'album di un utente richiede l'ambitophotoslibrary.appendonly. Per ulteriori informazioni sugli ambiti, consulta Ambiti di autorizzazione.

Tipi e dimensioni dei file accettati

Puoi caricare i tipi di file elencati in questa tabella.

Tipo di media Tipi di file accettati Dimensione massima del file
Foto AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP e alcuni file RAW. 200 MB
Video 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD, WMV. 20 GB

Passaggio 1: caricamento dei byte

Carica byte su Google utilizzando le richieste di caricamento. Una richiesta di caricamento riuscita restituisce un token di caricamento sotto forma di stringa di testo non elaborata. Utilizza questi token di caricamento per creare elementi multimediali con la chiamata batchCreate.

REST

Includi i seguenti campi nell'intestazione della richiesta POST:

Campi intestazione
Content-type Da impostare su application/octet-stream.
X-Goog-Upload-Content-Type Consigliata. Impostato sul tipo MIME dei byte che stai caricando. I tipi MIME comuni includono image/jpeg, image/png e image/gif.
X-Goog-Upload-Protocol Da impostare su raw.

Ecco un'intestazione della richiesta POST:

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-type: application/octet-stream
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: raw

Nel corpo della richiesta, includi il file binario: 

media-binary-data

Se questa richiesta POST ha esito positivo, un token di caricamento sotto forma di stringa di testo non elaborata viene restituito come corpo della risposta. Per creare elementi media, utilizza queste stringhe di testo nella chiamata batchCreate.

upload-token

Le dimensioni consigliate per le immagini sono inferiori a 50 MB. I file di dimensioni superiori a 50 MB sono soggetti a problemi di prestazioni.

L'API della Raccolta di Google Foto supporta i caricamenti riprendebili. Un caricamento con possibilità di ripresa consente di suddividere un file multimediale in più sezioni e caricarne una alla volta.

Passaggio 2: creazione di un elemento multimediale

Dopo aver caricato i byte dei file multimediali, puoi crearli come elementi multimediali in Google Foto utilizzando i token di caricamento. Un token di caricamento è valido per un giorno dalla creazione. Un elemento multimediale viene sempre aggiunto alla biblioteca dell'utente. Gli elementi multimediali possono essere aggiunti agli album creati dalla tua app. Per ulteriori informazioni, consulta gli scopi di autorizzazione.

Per creare nuovi elementi multimediali, chiama mediaItems.batchCreate specificando un elenco di newMediaItems. Ogni newMediaItem contiene un token di caricamento specificato all'interno di un simpleMediaItem e una descrizione facoltativa che viene mostrata all'utente.

Il campo della descrizione è limitato a 1000 caratteri e deve includere solo testo significativo creato dagli utenti. Ad esempio, "La nostra gita al parco" o "Cena di Natale". Non includere metadati come nomi file, tag programmatici o altro testo generato automaticamente.

Per ottenere le migliori prestazioni, riduci il numero di chiamate a mediaItems.batchCreate da effettuare includendo più elementi multimediali in una sola chiamata. Attendi sempre il completamento della richiesta precedente prima di effettuare una chiamata successiva per lo stesso utente.

Puoi creare un singolo elemento multimediale o più elementi multimediali nella raccolta di un utente specificando le descrizioni e i token di caricamento corrispondenti:

REST

Ecco l'intestazione della richiesta POST:

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer oauth2-token

Il corpo della richiesta deve specificare un elenco di newMediaItems.

{
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

Puoi anche specificare albumId e albumPosition per inserire elementi multimediali in una posizione specifica dell'album.

REST

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
    , ...
  ],
  "albumPosition": {
    "position": "after-media-item",
    "relativeMediaItemId": "media-item-id"
  }
}

Per maggiori dettagli sul posizionamento negli album, vedi Aggiungere arricchimenti.

Risposta alla creazione dell'articolo

La chiamata mediaItems.batchCreate restituisce il risultato per ogni elemento multimediale che hai provato a creare. L'elenco di newMediaItemResults indica lo stato e include il uploadToken per la richiesta. Un codice di stato diverso da zero indica un errore.

REST

Se tutti gli elementi multimediali sono stati creati correttamente, la richiesta restituisce lo stato HTTP 200 OK. Se non è possibile creare alcuni elementi multimediali, la richiesta restituisce lo stato HTTP 207 MULTI-STATUS per indicare il successo parziale.

{
  "newMediaItemResults": [
    {
      "uploadToken": "upload-token",
      "status": {
        "message": "Success"
      },
      "mediaItem": {
        "id": "media-item-id",
        "description": "item-description",
        "productUrl": "https://photos.google.com/photo/photo-path",
        "mimeType": "mime-type",
        "mediaMetadata": {
          "width": "media-width-in-px",
          "height": "media-height-in-px",
          "creationTime": "creation-time",
          "photo": {}
        },
        "filename": "filename"
      }
    },
    {
      "uploadToken": "upload-token",
      "status": {
        "code": 13,
        "message": "Internal error"
      }
    }
  ]
}

Se un elemento viene aggiunto correttamente, viene restituito un mediaItem contenente i relativi mediaItemId, productUrl e mediaMetadata. Per ulteriori informazioni, consulta Accedere agli elementi multimediali.

Se l'elemento multimediale è un video, deve essere elaborato per primo. Il mediaItem contiene un status all'interno del mediaMetadata che descrive lo stato di elaborazione del file video. Un file appena caricato restituisce inizialmente lo stato PROCESSING, prima di essere READY per l'utilizzo. Per maggiori dettagli, vedi Accedere agli elementi media.

Se si verifica un errore durante la chiamata, segui le Best practices e riprova a inviare la richiesta. Ti consigliamo di tenere traccia delle aggiunte riuscite in modo che l'immagine possa essere inserita nell'album nella posizione corretta durante la richiesta successiva. Per ulteriori informazioni, consulta Creare album.

I risultati vengono sempre restituiti nello stesso ordine in cui sono stati inviati i token di caricamento.

Best practice per i caricamenti

Le seguenti best practice e risorse ti aiutano a migliorare l'efficienza complessiva dei caricamenti:

  • Segui le best practice per la gestione degli errori e dei tentativi di nuovo invio, tenendo presente quanto segue:
    • Gli errori 429 possono verificarsi quando la tua quota è stata esaurita o se la frequenza è limitata per aver effettuato troppe chiamate troppo rapidamente. Assicurati di non chiamare batchCreate per lo stesso utente finché la richiesta precedente non è stata completata.
    • Gli errori 429 richiedono un ritardo minimo di 30s prima di riprovare. Utilizza una strategia di backoff esponenziale quando riprovi le richieste.
    • Gli errori 500 si verificano quando il server rileva un errore. Durante il caricamento, questo accade molto probabilmente perché vengono eseguite più chiamate di scrittura (ad esempio batchCreate) per lo stesso utente contemporaneamente. Controlla i dettagli della richiesta e non effettuare chiamate a batchCreate in parallelo.
  • Utilizza il flusso di caricamento ripristinabile per rendere i caricamenti più affidabili in caso di interruzioni della rete, riducendo l'utilizzo della larghezza di banda consentendoti di riprendere i caricamenti parzialmente completati. Questo è importante quando carichi da dispositivi mobili client o file di grandi dimensioni.

Inoltre, tieni presente i seguenti suggerimenti per ogni passaggio della procedura di caricamento: caricamento dei byte e poi creazione di elementi media.

Caricamento di byte

  • Il caricamento dei byte (per recuperare i token di caricamento) può essere eseguito in parallelo.
  • Imposta sempre il tipo MIME corretto nell'intestazione X-Goog-Upload-Content-Type per ogni chiamata di caricamento.

Creazione di elementi multimediali

  • Non effettuare chiamate in parallelo a batchCreate per un singolo utente.

    • Per ogni utente, effettua chiamate a batchCreate una dopo l'altra (in serie).
    • Per più utenti, effettua sempre chiamate batchCreate per ciascun utente una volta alla volta. Effettuare chiamate in parallelo solo per utenti diversi.

  • Includi il maggior numero possibile di NewMediaItems in ogni chiamata a batchCreate per ridurre al minimo il numero totale di chiamate da effettuare. Puoi includere al massimo 50 elementi.

  • Imposta un testo descrittivo significativo creato dagli utenti. Non includere nel campo della descrizione metadati come nomi di file, tag programmatici o altro testo generato automaticamente.

Procedura dettagliata di esempio

Questo esempio utilizza lo pseudocodice per illustrare il caricamento di elementi multimediali per più utenti. L'obiettivo è illustrare entrambe le fasi del processo di caricamento (caricamento di byte non elaborati e creazione di elementi multimediali), oltre a illustrare le best practice per creare un'integrazione dei caricamenti efficiente e resiliente.

Passaggio 1: carica i byte non elaborati

Per prima cosa, crea una coda per caricare i byte non elaborati dei tuoi elementi multimediali da tutti gli utenti. Monitora ogni uploadToken restituito per utente. Ricorda questi punti chiave:

  • Il numero di thread di caricamento simultanei dipende dall'ambiente operativo.
  • Valuta la possibilità di riordinare la coda di caricamento in base alle tue esigenze. Ad esempio, puoi assegnare la priorità ai caricamenti in base al numero di caricamenti rimanenti per utente, all'avanzamento complessivo di un utente o ad altri requisiti.

Pseudocodice

CREATE uploadQueue FROM users, filesToUpload
// Upload media bytes in parallel.
START multiple THREADS
  WHILE uploadQueue is not empty
    POP uploadQueue
    UPLOAD file for user
    GET uploadToken
    CHECK and HANDLE errors
    STORE uploadToken for user in uploadTokensQueue
  END

Passaggio 2: crea elementi multimediali

Nel passaggio 1 puoi caricare in parallelo più byte da più utenti, ma nel passaggio 2 puoi effettuare una sola chiamata per ogni utente alla volta.

Pseudocodice

// For each user, create media items once 50 upload tokens have been
// saved, or no more uploads are left per user.
WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user
  // Calls can be made in parallel for different users,
  // but only make a single call per user at a time.
  START new thread for (this) user if there is no thread yet
    POP 50 uploadTokens from uploadTokensQueue for user
    CALL mediaItems.batchCreate with uploadTokens
    WAIT UNTIL batchCreate call has completed
    CHECK and HANDLE errors (retry as needed)
  DONE.

Continua questa procedura fino al completamento di tutti i caricamenti e delle chiamate di creazione di contenuti multimediali.