Carica contenuti multimediali

Il caricamento di elementi multimediali è un processo in due fasi:

1. Carica i byte dei tuoi file multimediali su un server Google tramite i caricamenti endpoint. Questo 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 probabile 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 photoslibrary.appendonly ambito. Per ulteriori informazioni sugli ambiti, consulta Ambiti di autorizzazione.

Tipi e dimensioni di file accettati

Puoi caricare i tipi di file elencati in questa tabella.

Passaggio 1: caricamento dei byte

Caricare byte su Google tramite le richieste di caricamento. Richiesta di caricamento riuscita restituisce un token di caricamento sotto forma di stringa di testo non elaborato. Utilizza questi caricamenti token per creare elementi multimediali con la chiamata batchCreate.

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

media-binary-data

upload-token

Le dimensioni consigliate per le immagini sono inferiori a 50 MB. File più grandi di 50 MB potrebbero causare problemi di prestazioni.

L'API della libreria di Google Foto supporta i campi ripristinabili caricamenti. 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 soltanto a album creati dai tuoi dell'app. Per ulteriori informazioni, consulta Autorizzazione ambiti.

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

Il campo della descrizione è limitato a 1000 caratteri e deve includere solo creare testi significativi creati dagli utenti. Ad esempio, "La nostra gita al parco" o "Cena di Natale". Non includere metadati come nomi file, pubblicità programmatica o altro testo generato automaticamente.

Per un rendimento migliore, riduci il numero di chiamate a mediaItems.batchCreate da effettuare includendo più elementi multimediali in una sola chiamata. Attendi sempre fino a completata la 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:

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

{
  "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.

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

Per ulteriori dettagli sul posizionamento negli album, consulta la sezione Aggiungere arricchimenti.

Risposta alla creazione dell'elemento

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

{
  "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 i suoi mediaItemId, productUrl e mediaMetadata. Per ulteriori informazioni, vedi Accedere agli elementi multimediali.

Se l'elemento multimediale è un video, deve prima essere elaborato. mediaItem contiene un valore status all'interno di mediaMetadata che descrive l'elaborazione lo stato del file video. Un file appena caricato restituisce lo stato PROCESSING prima che sia READY per l'uso. Per maggiori dettagli, vedi Accedere ai contenuti multimediali. .

Se si verifica un errore durante la chiamata, segui le indicazioni della sezione pratiche e riprova a eseguire la richiesta. Tu potresti voler tenere traccia delle aggiunte andate a buon fine, in modo che l'immagine possa essere inserita all'interno dell'album nella posizione corretta durante la richiesta successiva. Per maggiori informazioni informazioni, consulta la sezione Creare album.

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

Best practice per i caricamenti

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

• Segui le istruzioni per i nuovi tentativi e la gestione degli errori più adeguate. pratiche, mantenendo tieni presente i seguenti punti:
  • 429 errori possono verificarsi quando la quota è stata esaurita o hai una frequenza limitata per aver effettuato troppe chiamate troppo rapidamente. Assicurati che non chiami batchCreate per lo stesso utente fino all'evento precedente La richiesta è stata completata.
  • 429 errori richiedono un ritardo minimo di 30s prima di poter riprovare. Utilizza una strategia di backoff esponenziale quando riprovi a inviare le richieste.
  • 500 errori si verificano quando il server rileva un errore. Durante il caricamento, questo è dovuto molto probabilmente all'esecuzione di più chiamate di scrittura (come batchCreate) per lo stesso utente contemporaneamente. Controlla i dettagli di la tua richiesta e non effettuare chiamate a batchCreate in parallelo.
• Usa il flusso di caricamento ripristinabile per rendere i tuoi caricamenti più affidabili in caso di interruzioni di rete, riducendo l'utilizzo della larghezza di banda consentendo di riprendere caricamenti parzialmente completati. Questo è importante quando carichi contenuti da dispositivi mobili client o 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 nel X-Goog-Upload-Content-Type intestazione per a ogni chiamata di caricamento.

Creazione di elementi multimediali in corso...

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

  • Per ogni utente, effettua chiamate a batchCreate una dopo l'altra (in seriale).
  • Per più utenti, effettua sempre chiamate batchCreate per ciascun utente una volta alla volta. 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 da realizzare. Puoi includere al massimo 50 elementi.

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

Procedura dettagliata di esempio

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

Passaggio 1: carica i byte non elaborati

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

• Il numero di thread di caricamento simultaneo dipende dal tuo funzionamento completamente gestito di Google Cloud.
• Valuta la possibilità di riordinare la coda di caricamento in base alle tue esigenze. Ad esempio, potresti assegna la priorità ai caricamenti in base al numero di caricamenti rimanenti per utente, una i progressi complessivi o altri requisiti dell'utente.

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 passaggio 2 puoi effettuare una sola chiamata per ciascun utente alla volta.

// 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 le chiamate di creazione di contenuti multimediali.