Funzioni nella libreria client App Engine per Cloud Storage

La libreria client App Engine per Cloud Storage fornisce le seguenti funzioni:

Funzioni

  • cloudstorage.copy2() copia il file specificato nel nuovo nome file specificato nello stesso bucket Cloud Storage.
  • cloudstorage.delete() elimina l'oggetto specificato dal bucket Cloud Storage.
  • cloudstorage.listbucket() elenca gli oggetti nel bucket Cloud Storage.
  • cloudstorage.open() apre un oggetto esistente nel bucket Cloud Storage per la lettura o la sovrascrittura oppure crea un nuovo oggetto, a seconda della modalità specificata.
  • cloudstorage.stat() fornisce informazioni sui metadati del file, come tipo di contenuto, dimensioni, timestamp, digest MD5 e intestazioni Cloud Storage.

Una volta richiamato cloudstorage.open() per restituire l'oggetto simile a un file che rappresenta l'oggetto Cloud Storage specificato, puoi utilizzare le funzioni di file Python standard, come write() e close(), per scrivere un oggetto nel bucket Cloud Storage o read() per leggere un oggetto dal bucket Cloud Storage.

Corsi

Funzioni

cloudstorage.copy2 (src, dst, metadata=None, retry_params=None)

Copia il file specificato nel nuovo nome file specificato, copiando per impostazione predefinita anche i metadati. Se vuoi, puoi sovrascrivere i metadati nella copia fornendo il parametro facoltativo metadata.

Genera cloudstorage.NotFoundError se l'oggetto Cloud Storage specificato non esiste o cloudstorage.AuthorizationError se l'autorizzazione non è riuscita.

Argomenti

src (obbligatorio)
Il nome completo del file Cloud Storage per l'oggetto, nel formato /bucket/object_name. Deve essere un nome file completo e può includere il delimitatore "/".
dst (obbligatorio)
Il nome completo del file Cloud Storage per la copia dell'oggetto, nel formato /bucket/object_name. Deve essere un nome file completo e può includere il delimitatore "/".
metadata= None (facoltativo)
Un dizionario di metadati per questa copia, ad esempio {'x-goog-meta-foo': 'bar'}. Se fornisci il parametro dei metadati, nessuno dei metadati originali viene copiato nel nuovo file. Se non vengono forniti metadati (None), vengono copiati tutti i metadati del file di origine.
retry_params= None (facoltativo)
Un oggetto RetryParams in cui fornisci le modifiche che vuoi apportare alle impostazioni predefinite di timeout e dei tentativi per questa chiamata.

Esempio

Per copiare un file, ma aggiungere nuovi metadati e ignorare l'errore se il file di origine non esiste:
import cloudstorage

try:
  cloudstorage.copy2('/my_bucket/README', '/my_bucket/README2', metadata={'x-goog-meta-zzzzz': 'zzzzz'})
except cloudstorage.NotFoundError:
  pass

Torna all'inizio


cloudstorage.delete (filename, retry_params=None)

Elimina il file specificato dal bucket Cloud Storage.

Genera cloudstorage.NotFoundError se l'oggetto Cloud Storage specificato non esiste.

Argomenti

filename (obbligatorio)
Il nome completo del file Cloud Storage per l'oggetto, nel formato /bucket/object_name. Deve essere un nome file completo e può includere il delimitatore "/".
retry_params= None (facoltativo)
Un oggetto RetryParams in cui fornisci le modifiche che vuoi apportare alle impostazioni predefinite di timeout e dei tentativi per questa chiamata.

Esempio

Per eliminare un file, ma ignorare l'errore quando il file non esiste:
import cloudstorage

try:
  cloudstorage.delete(filename)
except cloudstorage.NotFoundError:
  pass

Torna all'inizio


cloudstorage.listbucket (path_prefix, marker=None, max_keys=None, delimiter=None, retry_params=None)
Restituisce un oggetto iteratore del bucket. Questo iteratore restituisce un elenco ordinato di oggetti che corrispondono a tutti i filtri. Tieni presente che questa funzione è asincrona. Non blocca a meno che l'iteratore non venga chiamato prima che l'iteratore ottenga risultati.

Questa funzione opera in due modalità diverse a seconda che tu utilizzi l'argomento delimiter o meno:

  • Modalità normale (impostazione predefinita): elenca tutti i file nel bucket senza alcun concetto di gerarchia. Cloud Storage non ha gerarchie di directory reali.
  • Modalità di emulazione della directory: se specifichi l'argomento delimiter, viene utilizzato come separatore di percorso per emulare una gerarchia di directory.

Argomenti

path_prefix (obbligatorio)
Un percorso Cloud Storage nel formato /bucket o /bucket/prefix, ad esempio /bucket/foo/2001. Verranno restituiti solo gli oggetti il cui percorso completo inizia con path_prefix.
marker= None (facoltativo)
Stringa. Un altro prefisso di percorso. Verranno restituiti solo gli oggetti il cui percorso completo inizia lessicograficamente dopo il marcatore. Il file utilizzato come "marker" non viene restituito. Ad esempio, se vuoi che vengano elencati tutti i file a partire da superduperfoo3.txt, devi specificare il file immediatamente precedente a superduperfoo3.txt, ad esempio: 
stat = cloudstorage.listbucket("/my_bucket/foo", marker='/my_bucket/foo/superduperfoo2.txt')
 Un modo per utilizzare questo parametro è usarlo con max_keys per "sfogliare" i nomi dei file del bucket.
max_keys= None (facoltativo)
Numero intero. Specifica il numero massimo di oggetti da restituire. Utilizzalo se sai quanti oggetti vuoi. In caso contrario, la libreria client di Cloud Storage esegue automaticamente il buffering e la paginazione di tutti i risultati. Può essere utilizzato con marker per scorrere i nomi dei file in un bucket. 
stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size, marker=stat.filename)
delimiter= None (facoltativo)
Stringa. Attiva la modalità directory. Puoi specificare uno o più caratteri da utilizzare come separatore di directory.
retry_params= None (facoltativo)
Un oggetto RetryParams in cui fornisci le modifiche che vuoi apportare alle impostazioni predefinite di timeout e dei tentativi per questa chiamata.

Valore del risultato

Restituisce un iteratore di oggetti GCSFileStat sui file corrispondenti, ordinati per nome file. In modalità normale, gli oggetti GCSFileStat restituiti contengono i seguenti dati:

  • filename
  • etag (la rappresentazione esadecimale dell'hash MD5 dei contenuti del file)
  • st_size (lunghezza dei contenuti delle intestazioni)
  • st_ctime
  • is_dir

Nota:se la proprietà is_dir dell'oggetto GCSFileStat è True, l'unica altra proprietà dell'oggetto è filename. Se is_dir è False, allora GCSFileStat contiene anche tutte le altre proprietà.

Torna all'inizio


cloudstorage.open(filename, mode='r', content_type=None, options=None, read_buffer_size=storage_api.ReadBuffer.DEFAULT_BUFFER_SIZE, retry_params=None)

In modalità di lettura (r) apre l'oggetto Cloud Storage specificato per la lettura. In modalità di scrittura w, se il file specificato esiste, lo apre per la sovrascrittura (l'aggiunta non è supportata). Se il file non esiste, viene creato nel bucket specificato.

Al termine della scrittura, se vuoi leggere il file e/o archiviarlo in Cloud Storage, chiudilo utilizzando la funzione close. Non si tratta di un errore se non chiami close, ma il file non sarà leggibile o persistente in Cloud Storage.

Aumenti:

Argomenti

filename (obbligatorio)
Il file da aprire, nel formato /bucket/object. Ad esempio,/my_bucket/lyrics/southamerica/list5.txt.
mode (facoltativo)
Stringa. Specifica "r" per aprire un file per la lettura (impostazione predefinita). Specifica 'w' per aprire un file esistente per la sovrascrittura o per creare un nuovo file.

content_type: (facoltativo)
Stringa. Utilizzato solo in modalità di scrittura. Devi specificare il tipo MIME del file. Puoi specificare qualsiasi tipo MIME valido. Se non fornisci questo valore, Cloud Storage utilizza per impostazione predefinita il tipo binary/octet-stream quando mostra l'oggetto.
Opzioni: (facoltativo)

Diz. Utilizzato solo in modalità di scrittura. Le opzioni supportate sono x-goog-acl, x-goog-meta-, cache-control, content-disposition e content-encoding.

Se non fornisci un'opzione x-goog-acl, Cloud Storage utilizza l'ACL predefinita del bucket. I valori validi per x-goog-acl sono elencati nella documentazione di Cloud Storage per x-goog-acl.

Puoi specificare metadati dell'oggetto personalizzati utilizzando le intestazioni x-goog-meta-. Ad esempio:

gcs_file = cloudstorage.open(filename, 'w', content_type='text/plain', options={'x-goog-acl': 'private','x-goog-meta-foo': 'foo', 'x-goog-meta-bar': 'bar'})
read_buffer_size: (facoltativo)
Numero intero. Utilizzato solo in modalità di lettura. Se non imposti questo valore, viene utilizzata la dimensione predefinita del buffer (consigliata). Quando leggi, dovresti leggere entro read_buffer_size per un rendimento ottimale del prefetch.
retry_params= None (facoltativo)
Un oggetto RetryParams in cui fornisci le modifiche che vuoi apportare alle impostazioni predefinite di timeout e dei tentativi per questa chiamata.

Valore del risultato

Restituisce un buffer di lettura o scrittura, che supporta un'interfaccia simile a un file su cui puoi richiamare le funzioni standard di Python read, write e close. Questo buffer deve essere chiuso dopo che hai finito di leggere o scrivere.

Torna all'inizio


cloudstorage.stat(filename, retry_params=None)

Restituisce un oggetto GCSFileStat contenente i metadati del file.

Genera cloudstorage.NotFoundError se l'oggetto Cloud Storage specificato non esiste.

Argomenti

filename (obbligatorio)
Il file da aprire, nel formato /bucket/object. Ad esempio,/my_bucket/lyrics/southamerica/list5.txt
retry_params= None (facoltativo)
Un oggetto RetryParams in cui fornisci le modifiche che vuoi apportare alle impostazioni predefinite di timeout e dei tentativi per questa chiamata.

Valore del risultato

Restituisce un oggetto GCSFileStat contenente i metadati del file.

Torna all'inizio