Carica contenuti multimediali

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

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

Questi passaggi descrivono la procedura di caricamento di un singolo elemento multimediale. Se caricare più elementi multimediali (molto probabilmente per qualsiasi applicazione di produzione), Consulta le best practice per i caricamenti per migliorare la tua un'efficienza di caricamento efficiente.

Prima di iniziare

Ambiti di autorizzazione obbligatori

Il caricamento di elementi multimediali nella raccolta o nell'album di un utente richiede uno dei seguenti photoslibrary.appendonly o photoslibrary.

Gli elementi multimediali possono essere creati anche utilizzando l'ambito photoslibrary.sharing. A creare elementi con l'ambito photoslibrary.sharing, devi prima creare un album e contrassegnalo come condiviso utilizzando shareAlbum. Dopodiché potrai creare elementi multimediali condivisi con l'utente nell'album. Non puoi creare elementi direttamente in nella raccolta dell'utente o negli album non condivisi dall'app.

Quando elenchi gli album, la proprietà isWriteable indica se le tue applicazione dispone dell'accesso per creare contenuti multimediali in un determinato album.

Tipi e dimensioni di file accettati

Puoi caricare i tipi di file elencati nella tabella seguente.

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

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.

Nota: tutti gli elementi multimediali caricati su Google Foto tramite l'API vengono archiviata alla massima risoluzione in originale qualità. Se i tuoi caricamenti superino i 25 MB per utente, l'applicazione deve ricordare all'utente che questi caricamenti verranno conteggiati ai fini del calcolo dello spazio di archiviazione del loro Account Google.

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. Imposta il tipo MIME dei byte che stai caricando. I tipi MIME più comuni sono image/jpeg, image/png e image/gif.
X-Goog-Upload-Protocol	Da impostare su raw.

Ecco l'intestazione di una 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 programma binario del file:

media-binary-data

Se questa richiesta POST ha esito positivo, verrà creato un token di caricamento nel formato di una stringa di testo non elaborata, viene restituita come corpo della risposta. Per creare contenuti multimediali usa queste stringhe di testo nella chiamata batchCreate.

upload-token

Java

// Open the file and automatically close it after upload
try (RandomAccessFile file = new RandomAccessFile(pathToFile, "r")) {
  // Create a new upload request
  UploadMediaItemRequest uploadRequest =
      UploadMediaItemRequest.newBuilder()
              // The media type (e.g. "image/png")
              .setMimeType(mimeType)
              // The file to upload
              .setDataFile(file)
          .build();
  // Upload and capture the response
  UploadMediaItemResponse uploadResponse = photosLibraryClient.uploadMediaItem(uploadRequest);
  if (uploadResponse.getError().isPresent()) {
    // If the upload results in an error, handle it
    Error error = uploadResponse.getError().get();
  } else {
    // If the upload is successful, get the uploadToken
    String uploadToken = uploadResponse.getUploadToken().get();
    // Use this upload token to create a media item
  }
} catch (ApiException e) {
  // Handle error
} catch (IOException e) {
  // Error accessing the local file
}

PHP

try {
    // Create a new upload request by opening the file
    // and specifying the media type (e.g. "image/png")
    $uploadToken = $photosLibraryClient->upload(file_get_contents($localFilePath), null, $mimeType);
} catch (\GuzzleHttp\Exception\GuzzleException $e) {
    // Handle error
}

La dimensione file suggerita per le immagini è inferiore a 50 MB. I file di dimensioni superiori a 50 MB vengono soggetti a problemi di prestazioni.

L'API della libreria di Google Foto supporta caricamenti ripristinabili. Un curriculum consente di suddividere un file multimediale in più sezioni e caricarne uno alla volta.

Passaggio 2: crea un elemento multimediale

Dopo aver caricato i byte dei file multimediali, puoi crearli come file multimediali elementi in Google Foto utilizzando token di caricamento. Un token di caricamento è valido per un giorno dalla creazione. Un elemento multimediale viene sempre aggiunto libreria. Gli elementi multimediali possono essere aggiunto 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 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, "Il nostro viaggio al parco" o "Cena di Natale". Non includere metadati come nomi file, pubblicità programmatica o altro testo generato automaticamente.

Per un rendimento ottimale, riduci il numero di chiamate a mediaItems.batchCreate devi includere più elementi multimediali in una sola chiamata. Attendi sempre fino al 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"
      }
    }
   , ...
  ]
}

Java

try {
  // Create a NewMediaItem with the following components:
  // - uploadToken obtained from the previous upload request
  // - filename that will be shown to the user in Google Photos
  // - description that will be shown to the user in Google Photos
  NewMediaItem newMediaItem = NewMediaItemFactory
          .createNewMediaItem(uploadToken, fileName, itemDescription);
  List<NewMediaItem> newItems = Arrays.asList(newMediaItem);

  BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);
  for (NewMediaItemResult itemsResponse : response.getNewMediaItemResultsList()) {
    Status status = itemsResponse.getStatus();
    if (status.getCode() == Code.OK_VALUE) {
      // The item is successfully created in the user's library
      MediaItem createdItem = itemsResponse.getMediaItem();
    } else {
      // The item could not be created. Check the status and try again
    }
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $newMediaItems = [];
    // Create a NewMediaItem with the following components:
    // - uploadToken obtained from the previous upload request
    // - filename that will be shown to the user in Google Photos
    // - description that will be shown to the user in Google Photos
    $newMediaItems[0] = PhotosLibraryResourceFactory::newMediaItemWithDescriptionAndFileName(
            $uploadToken, $itemDescription, $fileName);

    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems);
    foreach ($response->getNewMediaItemResults() as $itemResult) {
        $status = $itemResult->getStatus();
        if ($status->getCode() != Code::OK) {
            // Error while creating the item.
        }
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Puoi aggiungere elementi multimediali alla raccolta e a un album specificando il album id. Per ulteriori informazioni, vedi Creare album.

Ogni album può contenere fino a 20.000 elementi multimediali. Richieste di creazione di contenuti multimediali gli elementi di un album che superano questo limite non andranno a buon fine.

REST

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

Java

try {
  // Create new media items in a specific album
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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

REST

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

Java

try {
  // Create new media items in a specific album, positioned after a media item
  AlbumPosition positionInAlbum = AlbumPositionFactory.createFirstInAlbum();
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems, positionInAlbum);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems,
        ['albumId' => $albumId, 'albumPosition' => $albumPosition]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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

Avviso: la chiamata batchCreate limita il numero di elementi multimediali creati in una chiamata a 50 elementi multimediali. Inoltre, sconsigliamo di usare più volte batchCreate verrà chiamata in parallelo per lo stesso utente.

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 .

REST

Se tutti gli elementi multimediali sono stati creati correttamente, la richiesta restituisce Stato HTTP 200 OK. Se alcuni elementi multimediali non possono essere creati, la richiesta restituisce lo stato HTTP 207 MULTI-STATUS per indicare 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"
      }
    }
  ]
}

Java

BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);

// The response contains a list of NewMediaItemResults
for (NewMediaItemResult result : response.getNewMediaItemResultsList()) {
  // Each result item is identified by its uploadToken
  String uploadToken = result.getUploadToken();
  Status status = result.getStatus();

  if (status.getCode() == Code.OK_VALUE) {
    // If the request is successful, a MediaItem is returned
    MediaItem mediaItem = result.getMediaItem();
    String id = mediaItem.getId();
    String productUrl = mediaItem.getProductUrl();
    // ...
  }
}

PHP

// The response from a call to batchCreateMediaItems returns a list of NewMediaItemResults
foreach ($response->getNewMediaItemResults() as $itemResult) {
    // Each result item is identified by its uploadToken
    $itemUploadToken = $itemResult->getUploadToken();
    // Verify the status of each entry to ensure that the item has been uploaded correctly
    $itemStatus = $itemResult->getStatus();
    if ($itemStatus->getCode() != Code::OK) {
        // Error when item is being created
    } else {
        // Media item is successfully created
        // Get the MediaItem object from the response
        $mediaItem = $itemResult->getMediaItem();
        // It contains details such as the Id of the item, productUrl
        $id = $mediaItem->getId();
        $productUrl = $mediaItem->getProductUrl();
        // ...
    }
}

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 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 andate a buon fine, in modo che l'immagine possa essere inserita all'interno dell'album nella posizione corretta durante la richiesta successiva. Per ulteriori informazioni le informazioni, vedi Creare album.

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

Nota: viene trattato lo stesso elemento multimediale (definito come gli stessi byte caricati). dello stesso oggetto. Ciò significa che viene restituito lo stesso elemento multimediale id, anche se viene indicato da un altro uploadToken.

Best practice per i caricamenti

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

• Utilizza una delle nostre librerie client supportate.
• Segui le best practice per nuovi tentativi e gestione degli errori. tenendo presente quanto segue:
  .
  • 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 un backoff esponenziale quando si ritentano 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. durante il caricamento di file di grandi dimensioni.

Inoltre, tieni in considerazione i seguenti suggerimenti per ogni passaggio della procedura di caricamento: il caricamento di byte e la creazione di elementi multimediali.

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 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 batchCreate chiamate per ognuno uno dopo l'altro. 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 dai tuoi 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 della procedura 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.

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, al passaggio 2 puoi effettuare una sola chiamata per ciascun 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 le chiamate di creazione di contenuti multimediali.