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, ad esempio tipo di contenuto, dimensioni, timestamp, digest MD5 e intestazioni Cloud Storage.

Una volta invocato 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 file completo di Cloud Storage dell'oggetto, nel formato /bucket/object_name. Deve essere un nome file completo e può includere il delimitatore "/".
dst (obbligatorio)
Il nome file completo di 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 metadata, nessuno dei metadati originali viene copiato nel nuovo file. Se non vengono forniti metadati, (None), tutti i metadati del file di origine vengono copiati.
retry_params= None (facoltativo)
Un oggetto RetryParams in cui specificare le modifiche da apportare alle impostazioni predefinite di timeout e riprova 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 file completo di Cloud Storage dell'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 specificare le modifiche da apportare alle impostazioni predefinite di timeout e riprova 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 si 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 o meno l'argomento delimiter:

  • Modalità normale (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, questo viene utilizzato come separatore di percorso per emulare una gerarchia di directory.

Argomenti

path_prefix (obbligatorio)
Un percorso Cloud Storage di formato /bucket o /bucket/prefix, ad esempio /bucket/foo/2001. Verranno riportati solo gli oggetti il cui percorso completo inizia con path_prefix.
marker= Nessuno (facoltativo)
Stringa. Un altro prefisso di percorso. Verranno restituiti solo gli oggetti il cui percorso completo inizia in modo lessicografico dopo l'indicatore. Il file utilizzato come "marker" non viene restituito. Ad esempio, se vuoi che tutti i file elencati a partire da superduperfoo3.txt vengano elencati, specifica il file immediatamente precedente superduperfoo3.txt, ad esempio: 
stat = cloudstorage.listbucket("/my_bucket/foo", marker='/my_bucket/foo/superduperfoo2.txt')
 Un modo per utilizzare questo parametro è utilizzarlo 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 file in un bucket. 
stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size, marker=stat.filename)
delimiter= Nessuno (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 specificare le modifiche da apportare alle impostazioni predefinite di timeout e riprova per questa chiamata.

Valore del risultato

Restituisce un iteratore di oggetti GCSFileStat relativi ai file corrispondenti, ordinati per nome file. In modalità normale, gli oggetti GCSFileStat restituiti hanno 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à nell'oggetto è filename. Se is_dir è False, 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, viene aperto per una sovrascrittura (l'accodamento non è supportato). Se il file non esiste, viene creato nel bucket specificato.

Al termine della scrittura, se vuoi leggere il file e/o archiviarlo su Cloud Storage, chiudilo utilizzando la funzione close. Non si tratta di un errore se non chiami close, ma il file non sarà leggibile o mantenuto 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 in lettura (valore predefinito). Specifica 'w' per aprire un file esistente da sovrascrivere 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 serve l'oggetto.
options: (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 degli oggetti 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 del buffer predefinita (opzione consigliata). Quando leggi, dovresti leggere per read_buffer_size per un rendimento ottimale del pre-caricamento.
retry_params= None (facoltativo)
Un oggetto RetryParams in cui specificare le modifiche da apportare alle impostazioni predefinite di timeout e riprova per questa chiamata.

Valore del risultato

Restituisce un buffer di lettura o scrittura, supportando un'interfaccia simile a un file su cui puoi invocare le funzioni read, write e close di Python standard. Questo buffer deve essere chiuso al termine della lettura o della scrittura.

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 specificare le modifiche da apportare alle impostazioni predefinite di timeout e riprova per questa chiamata.

Valore del risultato

Restituisce un oggetto GCSFileStat contenente i metadati del file.

Torna all'inizio