Carica contenuti multimediali

Il caricamento degli elementi multimediali è una procedura in due passaggi:

  1. Carica i byte dei tuoi file multimediali su un server Google utilizzando l'endpoint uploads. Restituisce 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 carichi 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 obbligatori

Il caricamento di elementi multimediali nella raccolta o nell'album di un utente richiede l'ambito photoslibrary.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, 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 i 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 di 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 di 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, viene restituito un token di caricamento sotto forma di stringa di testo non elaborato come corpo della risposta. Per creare elementi multimediali, utilizza queste stringhe di testo nella chiamata batchCreate.

upload-token

Le dimensioni file 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 Google Photos Library supporta i caricamenti ripresi. Un caricamento ripristinabile ti consente di dividere un file multimediale in più sezioni e caricare una sezione alla volta.

Passaggio 2: crea 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 dopo la creazione. Un elemento multimediale viene sempre aggiunto alla raccolta dell'utente. Gli elementi multimediali possono essere aggiunti solo agli album creati dalla tua app. Per ulteriori informazioni, consulta la sezione Ambiti 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 di file, tag programmatici o altro testo generato automaticamente.

Per ottenere prestazioni ottimali, riduci il numero di chiamate a mediaItems.batchCreate che devi 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 miglioramenti.

Risposta alla creazione dell'elemento

La chiamata mediaItems.batchCreate restituisce il risultato per ciascuno degli elementi multimediali che hai tentato di 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 che l'operazione è riuscita parzialmente.

{
  "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 che contiene il relativo mediaItemId, productUrl e mediaMetadata. Per maggiori informazioni, vedi 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 prima lo stato PROCESSING, prima di essere READY per l'utilizzo. Per maggiori dettagli, vedi Accedere agli elementi multimediali.

Se si verifica un errore durante la chiamata, segui le best practice 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 saperne di più, 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 dei tentativi e degli errori, tenendo presente quanto segue:
    • Gli errori 429 possono verificarsi quando la quota è stata esaurita o quando è stato applicato un limite di frequenza per aver effettuato troppe chiamate troppo rapidamente. Assicurati di non chiamare batchCreate per lo stesso utente prima che la richiesta precedente sia 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 problema si verifica molto probabilmente perché sono state effettuate più chiamate di scrittura (ad esempio batchCreate) per lo stesso utente contemporaneamente. Controlla i dettagli della tua 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 di rete, riducendo l'utilizzo della larghezza di banda, in quanto ti consente di riprendere i caricamenti completati parzialmente. Questo è importante quando carichi file da dispositivi mobili client o quando carichi file di grandi dimensioni.

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

Byte caricati

  • 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 dopo l'altra. Effettua chiamate solo per utenti diversi in parallelo.

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

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

Esempio di procedura dettagliata

Questo esempio utilizza pseudocodice per illustrare il caricamento di elementi multimediali per più utenti. L'obiettivo è descrivere entrambi i passaggi della procedura di caricamento (caricamento di byte non elaborati e creazione di elementi multimediali) e dettagliare le best practice per creare un'integrazione di caricamento efficiente e resiliente.

Passaggio 1: carica i byte non elaborati

Per prima cosa, crea una coda per caricare i byte non elaborati per i tuoi elementi multimediali da tutti i tuoi utenti. Tieni traccia di 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 esigenze. Ad esempio, potresti dare la priorità ai caricamenti in base al numero di caricamenti rimanenti per utente, ai progressi complessivi 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 più byte da più utenti in parallelo, 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 finché non sono state completate tutte le chiamate di caricamento e creazione di contenuti multimediali.