Questa pagina è stata tradotta dall'API Cloud Translation.

Caricamento delle immagini in corso...

L'API Play Games Services Publishing ti consente di caricare un'immagine per una risorsa del gioco.

Opzioni di caricamento

L'API Play Games Services Publishing ti consente di caricare determinati tipi di dati binari o contenuti multimediali. Le caratteristiche specifiche dei dati che puoi caricare sono specificate nella pagina di riferimento per qualsiasi metodo che supporta i caricamenti multimediali:

Dimensioni massime del file di caricamento: la quantità massima di dati che puoi archiviare con questo metodo.
Tipi MIME multimediali accettati: i tipi di dati binari che puoi archiviare utilizzando questo metodo.

Puoi effettuare richieste di caricamento in uno dei seguenti modi: Specifica il metodo che stai utilizzando con il parametro di richiesta uploadType.

Caricamento semplice: uploadType=media. Per trasferimenti rapidi di file più piccoli, ad esempio non più di 5 MB.
Caricamento multiparte: uploadType=multipart. Per un trasferimento rapido di metadati e file più piccoli; trasferisci il file insieme ai metadati che lo descrivono, il tutto in un'unica richiesta
Caricamento ripristinabile: uploadType=resumable. Per un trasferimento affidabile, in particolar modo importante per i file di dimensioni maggiori. Con questo metodo, devi utilizzare una richiesta di avvio di una sessione, che facoltativamente può includere metadati. Si tratta di una buona strategia da utilizzare per la maggior parte delle applicazioni, dato che funziona anche per file più piccoli al costo di una richiesta HTTP aggiuntiva per caricamento.

Quando carichi contenuti multimediali, devi utilizzare un URI speciale. Infatti, i metodi che supportano i caricamenti multimediali hanno due endpoint URI:

L'URI /upload, per i contenuti multimediali. Il formato dell'endpoint di caricamento è l'URI della risorsa standard con prefisso "/upload". Utilizza questo URI quando trasferisci i dati multimediali.
Esempio: POST /upload/games/v1configuration/images/resourceId/imageType/imageType
L'URI della risorsa standard, per i metadati. Se la risorsa contiene campi di dati, questi vengono utilizzati per archiviare i metadati che descrivono il file caricato. Puoi utilizzare questo URI durante la creazione o l'aggiornamento dei valori dei metadati.
Esempio: POST /games/v1configuration/images/resourceId/imageType/imageType

Caricamento semplice

Il metodo più semplice per caricare un file è semplicemente effettuare una richiesta di caricamento. Questa opzione è ideale quando:

Il file è abbastanza piccolo da poter essere caricato completamente se la connessione non riesce.
Non sono presenti metadati da inviare. Questo potrebbe verificarsi se prevedi di inviare metadati per questa risorsa in una richiesta separata o se non sono supportati o disponibili metadati.

Per utilizzare il caricamento semplice, effettua una richiesta POST o PUT all'URI /upload del metodo e aggiungi il parametro di ricerca uploadType=media. Ad esempio:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media

Le intestazioni HTTP da utilizzare per le richieste di caricamento semplici includono:

Content-Type. Imposta uno dei tipi di dati multimediali caricati per il metodo, specificati nel riferimento dell'API.
Content-Length. Imposta il numero di byte che stai caricando. Non è obbligatorio se utilizzi la codifica di trasferimento a blocchi.

Esempio: caricamento semplice

L'esempio che segue mostra l'utilizzo di una semplice richiesta di caricamento per l'API Play Games Services Publishing.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/png
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

PNG data

Se la richiesta ha esito positivo, il server restituisce il codice di stato HTTP 200 OK insieme a tutti i metadati:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

Caricamento di più parti

Se disponi di metadati che vuoi inviare insieme ai dati da caricare, puoi effettuare una singola richiesta multipart/related. Questa è una buona scelta se i dati che invii sono sufficientemente piccoli da consentire il caricamento completo in caso di problemi di connessione.

Per utilizzare il caricamento a più parti, effettua una richiesta POST o PUT all'URI /upload del metodo e aggiungi il parametro di ricerca uploadType=multipart, ad esempio:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart

Le intestazioni HTTP di primo livello da utilizzare per le richieste di caricamento con più parti includono:

Content-Type. Imposta l'opzione su più parti/correlati e includi la stringa di confine che utilizzi per identificare le parti della richiesta.
Content-Length. Imposta il numero totale di byte nel corpo della richiesta. La parte multimediale della richiesta deve essere inferiore alla dimensione massima del file specificata per questo metodo.

Il corpo della richiesta è formattato come un tipo di contenuto multipart/related [RFC2387] e contiene esattamente due parti. Le parti sono identificate da una stringa di confine e la stringa di confine finale è seguita da due trattini.

Ogni parte della richiesta con più parti richiede un'intestazione Content-Type aggiuntiva:

Parte dei metadati: deve essere prima di tutto e Content-Type deve corrispondere a uno dei formati di metadati accettati.
Parte multimediale:deve essere secondaria e Content-Type deve corrispondere a uno dei tipi MIME multimediali accettati per il metodo.

Consulta il riferimento dell'API per l'elenco dei tipi di MIME multimediali accettati e i limiti di dimensioni per i file caricati.

Nota: per creare o aggiornare solo la parte dei metadati senza caricare i dati associati, invia una richiesta POST o PUT all'endpoint della risorsa standard: https://www.googleapis.com/games/v1configuration/images/resourceId/imageType/imageType

Esempio: caricamento a più parti

L'esempio che segue mostra una richiesta di caricamento di più parti per l'API Play Games Services Publishing.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

--foo_bar_baz
Content-Type: image/png

PNG data
--foo_bar_baz--

Se la richiesta ha esito positivo, il server restituisce il codice di stato HTTP 200 OK insieme a tutti i metadati:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

Caricamento ripristinabile

Per caricare i file di dati in modo più affidabile, puoi utilizzare il protocollo di caricamento ripristinabile. Questo protocollo consente di riprendere un'operazione di caricamento dopo che un errore di comunicazione ha interrotto il flusso di dati. Questa procedura è particolarmente utile se devi trasferire file di grandi dimensioni e la probabilità di interruzione della rete o altri errori di trasmissione è elevata, ad esempio durante il caricamento da un'app client per dispositivi mobili. Può anche ridurre l'utilizzo della larghezza di banda in caso di errori di rete perché non è necessario riavviare i caricamenti di file di grandi dimensioni dall'inizio.

La procedura per utilizzare il caricamento ripristinabile include i seguenti passaggi:

Avvia una sessione ripristinabile. Invia una richiesta iniziale all'URI di caricamento che include i metadati, se presenti.
Salva l'URI di sessione ripristinabile. Salva l'URI della sessione restituito nella risposta della richiesta iniziale; lo utilizzerai per le richieste rimanenti in questa sessione.
Carica il file. Invia il file multimediale all'URI della sessione ripristinabile.

Inoltre, le app che usano il caricamento ripristinabile devono avere il codice per riprendere un caricamento interrotto. Se un caricamento viene interrotto, scopri quanti dati sono stati ricevuti correttamente e riprendilo a partire da quel momento.

Nota: un URI di caricamento scade dopo una settimana.

Passaggio 1: avvia una sessione ripristinabile

Per avviare un caricamento ripristinabile, effettua una richiesta POST o PUT all'URI /upload del metodo e aggiungi il parametro di ricerca uploadType=resumable, ad esempio:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable

Per questa richiesta di avvio, il corpo è vuoto o contiene solo metadati; trasferirai i contenuti effettivi del file che vuoi caricare nelle richieste successive.

Utilizza le seguenti intestazioni HTTP con la richiesta iniziale:

X-Upload-Content-Type. Imposta il tipo MIME multimediale dei dati di caricamento da trasferire nelle richieste successive.
X-Upload-Content-Length. Imposta il numero di byte dei dati di caricamento da trasferire nelle richieste successive. Se la lunghezza è sconosciuta al momento della richiesta, puoi omettere questa intestazione.
Se fornisci i metadati: Content-Type. Impostato in base al tipo di dati dei metadati.
Content-Length. Imposta il numero di byte forniti nel corpo di questa richiesta iniziale. Non è obbligatorio se utilizzi la codifica di trasferimento a blocchi.

Consulta il riferimento dell'API per l'elenco dei tipi di MIME multimediali accettati e i limiti di dimensioni per i file caricati.

Esempio: richiesta di avvio di sessione ripresabile

L'esempio seguente mostra come avviare una sessione per la ripresa dell'API Play Games Services.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: image/png
X-Upload-Content-Length: 2000000

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

Nota: per una richiesta di aggiornamento ripristinabile iniziale senza metadati, lascia vuoto il corpo della richiesta e imposta l'intestazione Content-Length su 0.

La prossima sezione descrive come gestire la risposta.

Passaggio 2: salva l'URI di sessione ripristinabile

Se la richiesta di avvio della sessione ha esito positivo, il server API risponde con un codice di stato HTTP 200 OK. Inoltre, fornisce un'intestazione Location che specifica l'URI di sessione ripristinabile. L'intestazione Location, mostrata nell'esempio seguente, include una porzione di parametro di ricerca upload_id che fornisce l'ID caricamento univoco da utilizzare per questa sessione.

Esempio: risposta di avvio della sessione ripresabile

Ecco la risposta alla richiesta nel passaggio 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

Il valore dell'intestazione Location, come mostrato nella risposta di esempio sopra, è l'URI della sessione che utilizzerai come endpoint HTTP per eseguire il caricamento effettivo del file o eseguire query sullo stato di caricamento.

Copia e salva l'URI della sessione per poterlo utilizzare per le richieste successive.

Passaggio 3. Carica il file

Per caricare il file, invia una richiesta PUT all'URI di caricamento ottenuto nel passaggio precedente. Il formato della richiesta di caricamento è:

PUT session_uri

Le intestazioni HTTP da utilizzare per le richieste di caricamento di file ripristinabili includono Content-Length. Impostalo sul numero di byte che stai caricando nella richiesta, che in genere corrisponde alle dimensioni del file di caricamento.

Esempio: richiesta di caricamento di file ripristinabile

Ecco una richiesta ripristinabile per caricare l'intero file PNG da 2.000.000 di byte per l'esempio corrente.

PUT https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/png

bytes 0-1999999

Se la richiesta ha esito positivo, il server risponde con un HTTP 201 Created, insieme a tutti i metadati associati a questa risorsa. Se la richiesta iniziale della sessione ripristinabile fosse stata un PUT, per aggiornare una risorsa esistente, la risposta corretta sarebbe 200 OK, insieme a tutti i metadati associati a questa risorsa.

Se la richiesta di caricamento viene interrotta o se ricevi dal server una risposta HTTP 503 Service Unavailable o qualsiasi altra risposta 5xx, segui la procedura descritta nella sezione Riprendere un caricamento interrotto.

Caricare il file in blocchi

Con i caricamenti ripristinabili, puoi suddividere un file in blocchi e inviare una serie di richieste per caricare ogni blocco in sequenza. Questo non è l'approccio preferito perché esistono costi per le prestazioni associati alle richieste aggiuntive e generalmente non è necessario. Tuttavia, potrebbe essere necessario utilizzare la suddivisione per ridurre la quantità di dati trasferiti in ogni singola richiesta. Questa operazione è utile quando esiste un limite di tempo fisso per le singole richieste, come avviene per alcune classi di richieste di Google App Engine. Ti permette inoltre di fornire indicazioni per lo stato di avanzamento del caricamento per i browser precedenti che non lo supportano per impostazione predefinita.

Espandi per ulteriori informazioni

Se stai caricando i dati in blocchi, sono necessarie anche l'intestazione Content-Range e l'intestazione Content-Length per i caricamenti completi di file:

Content-Length. Imposta la dimensione del blocco o, possibilmente, meno, come per l'ultima richiesta.
Content-Range: per mostrare i byte del file che stai caricando. Ad esempio, Content-Range: bytes 0-524287/2000000 indica che stai fornendo i primi 524.288 byte (256 x 1024 x 2) in un file da 2.000.000 di byte.

Limitazione della dimensione del blocco: tutti i blocchi devono avere un multiplo di 256 kB (256 x 1024 byte), ad eccezione del blocco finale che completa il caricamento. Se utilizzi la suddivisione, è importante mantenere le dimensioni del componente il più grandi possibile per mantenere efficiente il caricamento.

Esempio: richiesta di caricamento di file suddivisi in blocchi

Una richiesta che invia i primi 524.288 byte potrebbe avere il seguente aspetto:

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: image/png
Content-Range: bytes 0-524287/2000000

bytes 0-524288

Se la richiesta ha esito positivo, il server risponde con 308 Resume Incomplete, insieme a un'intestazione Range che identifica il numero totale di byte archiviati finora:

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

Usa il valore superiore restituito nell'intestazione Range per determinare da dove iniziare il blocco successivo. Continua a PUT ogni blocco di file fino al caricamento dell'intero file.

Se la richiesta di un blocco PUT viene interrotta o se ricevi dal server una risposta HTTP 503 Service Unavailable o qualsiasi altra risposta 5xx, segui la procedura descritta in riprendere un caricamento interrotto. Tuttavia, invece di caricare il resto del file, continua semplicemente a caricare i blocchi da quel momento in poi.

Note importanti:

Assicurati di utilizzare l'intestazione Range nella risposta per determinare da dove iniziare il blocco successivo; non dare per scontato che il server abbia ricevuto tutti i byte inviati nella richiesta precedente.
Ogni URI di caricamento ha una durata limitata e scade (entro un giorno circa, se non viene utilizzato). Per questo motivo, ti consigliamo di avviare un caricamento ripristinabile non appena ottieni l'URI di caricamento e di riprendere un caricamento interrotto subito dopo l'interruzione.
Se invii una richiesta con un ID sessione di caricamento scaduto, il server restituisce un codice di stato 404 Not Found. Quando si verifica un errore irreversibile nella sessione di caricamento, il server restituisce un codice di stato 410 Gone. In questi casi, devi avviare un nuovo caricamento ripristinabile, ottenere un nuovo URI di caricamento e avviare il caricamento dall'inizio utilizzando il nuovo endpoint.

Una volta completato il caricamento, il server risponde con un HTTP 201 Created insieme a tutti i metadati associati a questa risorsa. Se questa richiesta fosse l'aggiornamento di un'entità esistente invece di crearne una nuova, il codice di risposta HTTP per un caricamento completato sarebbe stato 200 OK.

Riprendi un caricamento interrotto

Se una richiesta di caricamento viene terminata prima di ricevere una risposta o se ricevi una risposta HTTP 503 Service Unavailable dal server, devi riprendere il caricamento interrotto. Per farlo:

Stato richiesta. Esegui una query sullo stato attuale del caricamento inviando una richiesta PUT vuota all'URI di caricamento. Per questa richiesta, le intestazioni HTTP devono includere un'intestazione Content-Range che indichi che la posizione corrente nel file è sconosciuta. Ad esempio, imposta Content-Range su */2000000 se la lunghezza totale del file è di 2.000.000. Se non conosci le dimensioni totali del file, imposta Content-Range su */*.
Nota: puoi richiedere lo stato tra i blocchi, non solo se il caricamento viene interrotto. Questo è utile, ad esempio, se vuoi mostrare indicazioni di avanzamento del caricamento per i browser precedenti.
Carica il numero di byte caricati. Elabora la risposta dalla query dello stato. Il server utilizza l'intestazione Range nella sua risposta per specificare i byte ricevuti finora. Ad esempio, un'intestazione Range di 0-299999 indica che sono stati ricevuti i primi 300.000 byte del file.
Carica i dati rimanenti. Infine, ora che sai dove riprendere la richiesta, invia i dati rimanenti o il blocco corrente. Tieni presente che in entrambi i casi devi trattare i dati rimanenti come blocchi separati, quindi dovrai inviare l'intestazione Content-Range quando riprendi il caricamento.

Esempio: riprendere il caricamento interrotto

1) Richiedi lo stato del caricamento.

La seguente richiesta utilizza l'intestazione Content-Range per indicare che la posizione corrente nel file da 2.000.000 di byte è sconosciuta.

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2) Estrai il numero di byte caricati finora dalla risposta.

La risposta del server utilizza l'intestazione Range per indicare che finora il file ha ricevuto i primi 43 byte. Usa il valore superiore dell'intestazione Range per determinare da dove iniziare il caricamento.

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

Nota: se il caricamento è completo, la risposta potrebbe essere 201 Created o 200 OK. Questo può accadere se la connessione si è interrotta dopo il caricamento di tutti i byte, ma prima che il client ricevesse una risposta dal server.

3) Riprendi il caricamento dal punto in cui è stato interrotto.

La richiesta seguente ripristina il caricamento inviando i byte rimanenti del file, a partire dal byte 43.

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

Best practice

Quando carichi contenuti multimediali, è utile essere a conoscenza di alcune best practice relative alla gestione degli errori.

Riprendi o riprova i caricamenti non riusciti a causa di interruzioni della connessione o di eventuali errori di 5xx, tra cui:
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Utilizza una strategia di backoff esponenziale se viene restituito un errore del server 5xx durante la ripresa o la nuova richiesta di caricamento. Questi errori possono verificarsi se un server si sovraccarica. Il backoff esponenziale può aiutare a ridurre questo tipo di problemi durante i periodi di volume elevato di richieste o con traffico di rete intenso.
Gli altri tipi di richieste non dovrebbero essere gestiti da un backoff esponenziale, ma puoi comunque riprovare alcune. Quando provi a eseguire nuovamente queste richieste, limita il numero di volte che puoi ripeterle. Ad esempio, il codice potrebbe limitare al massimo dieci tentativi prima di segnalare un errore.
Gestisci gli errori 404 Not Found e 410 Gone quando esegui caricamenti ripristinabili avviando l'intero caricamento dall'inizio.

Backoff esponenziale

Il backoff esponenziale è una strategia di gestione degli errori standard per le applicazioni di rete in cui il client prova periodicamente una richiesta non riuscita per un periodo di tempo crescente. Se un volume elevato di richieste o un elevato traffico di rete causano la restituzione di errori da parte del server, il backoff esponenziale può essere una buona strategia per la gestione di tali errori. Al contrario, non rappresenta una strategia pertinente per la gestione di errori non correlati al volume di rete o di tempi di risposta, come credenziali di autorizzazione non valide o errori di file non trovati.

Se utilizzato correttamente, il backoff esponenziale aumenta l'efficienza dell'utilizzo della larghezza di banda, riduce il numero di richieste richieste per ottenere una risposta corretta e massimizza la velocità effettiva delle richieste in ambienti simultanei.

Il flusso per l'implementazione di un backoff esponenziale semplice è il seguente:

Inviare una richiesta all'API.
Ricevi una risposta HTTP 503 che indica che dovresti riprovare.
Attendi 1 secondo + numero_casuale_di_millisecondi e riprova la richiesta.
Ricevi una risposta HTTP 503 che indica che dovresti riprovare.
Attendi 2 secondi + numero_casuale_di_millisecondi e riprova la richiesta.
Ricevi una risposta HTTP 503 che indica che dovresti riprovare.
Attendi 4 secondi + numero_casuale_di_millisecondi e riprova la richiesta.
Ricevi una risposta HTTP 503 che indica che dovresti riprovare.
Attendi 8 secondi + numero_casuale_di_millisecondi e riprova la richiesta.
Ricevi una risposta HTTP 503 che indica che dovresti riprovare.
Attendi 16 secondi + numero_casuale_di_millisecondi e riprova la richiesta.
Interrompi. Segnala o registra un errore.

Nel flusso sopra riportato, il valore casuale_numero_millisecondi è un numero casuale di millisecondi inferiore o uguale a 1000. Questo è necessario, poiché l'introduzione di un piccolo ritardo casuale consente di distribuire il carico in modo più uniforme ed evitare la possibilità di sovraccaricare il server. Il valore di random_number_milliseconds deve essere ridefinito dopo ogni attesa.

Nota: l'attesa è sempre (2 ^ n) + numero_casuale_di_millisecondi, dove n è un numero intero in aumento monotonico inizialmente definito come 0. Il numero intero viene aumentato di 1 per ogni iterazione (ogni richiesta).

L'algoritmo è impostato per terminare quando n è 5. Questo limite impedisce ai client di riprovare all'infinito e comporta un ritardo totale di circa 32 secondi prima che una richiesta venga considerata "un errore irreversibile." È possibile un numero massimo di nuovi tentativi, soprattutto se è in corso un caricamento lungo. Assicurati solo di limitare il ritardo dei nuovi tentativi in modo ragionevole, ad esempio in meno di un minuto.