Storage configs

La risorsa di configurazione della memoria descrive dove l'API può memorizzare i dati appartenenti ai risultati dei sondaggi. Tutte le posizioni specificate nelle configurazioni di archiviazione devono essere un bucket di archiviazione nel cloud in Google Cloud Storage o Amazon S3 (AWS) .

attributi

tipi

gs

il tipo di configurazione di archiviazione di Google Cloud Storage . Richiede credenziali dell'account di servizio.

s3

il tipo di configurazione di archiviazione Amazon S3 (AWS) . Richiede credenziali utente AWS.

URL

L'attributo url segue il formato:

<type>://<bucket name>/<path within bucket>

Ad esempio, dato che abbiamo un bucket in Google Cloud Storage con il nome "my-bucket" e vogliamo che l'API pubblichi in una cartella all'interno di questo bucket denominata "results", l' url sarà simile a:

gs://my-bucket/results

Credenziali

Credenziali di Google Cloud Storage

L'API prevede che l'attributo delle credentials sia un dizionario con il formato:

{
    "type": "service_account",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "client_id": "<Google Cloud Platform client ID>",
    "token_uri": "https://oauth2.googleapis.com/token",
    "project_id": "<Google Cloud Platform project ID>",
    "private_key": "<Service Account private key>",
    "client_email": "<Service Account ID>.iam.gserviceaccount.com",
    "private_key_id": "<Service Account private key ID>",
    "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/<Service Account ID>.iam.gserviceaccount.com",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs"
}

Questo corrisponde esattamente al file JSON di uscita quando si crea un codice di account di servizio tramite la console di Google Cloud Platform.

Per semplificare l'impostazione di una configurazione di archiviazione utilizzando le credenziali del file JSON esportate, ricloud-py include un semplice comando cli:

ricloud storage-config create --url "gs://<bucket name>" --credentials <path to JSON file>

Credenziali Amazon S3

L'API prevedeva che l'attributo delle credentials fosse un dizionario con il formato:

{
    "user_name": "<aws user name>",
    "access_key_id": "<aws user access key ID>",
    "secret_access_key": "<aws user secret access key>",
}

Nel payload delle credenziali riportato sopra, il parametro user_name corrisponde al nome utente dell'utente IAM AWS a cui appartiene la chiave di accesso. Questo può essere utile da includere a fini amministrativi e di controllo.

Questo può essere costruito manualmente dai dettagli mostrati nella console AWS o dal file CSV esportabile tramite il comando cli di ricloud-py :

ricloud storage-config create --url "s3://<bucket name>" --credentials <path to CSV file>

URL firmati

Gli URL firmati sono collegamenti pre-autorizzati a tempo limitato per accedere a un elemento in un bucket di archiviazione cloud. Consentono alle implementazioni di fornire un accesso sicuro a un elemento specifico a cui altrimenti il client non avrebbe credenziali di accesso o nessuna credenziale.

Quando gli URL firmati sono abilitati su una configurazione di archiviazione, tutti i risultati pubblicati utilizzando tale configurazione avranno popolato l'attributo signed_url . Vedi gli attributi dei risultati per maggiori dettagli.

Gli URL firmati sono supportati sia da Google Cloud Storage ( link a documenti URL firmati GCS ) sia da AWS S3 ( link a documenti S3 ).

Un ulteriore requisito per gli URL firmati è che l'utente associato alle credenziali di configurazione dell'archiviazione deve disporre delle autorizzazioni di lettura sugli oggetti nel bucket. In GCS questo è il ruolo "Visualizzatore oggetti di archiviazione". In S3 è l'azione della politica "s3: GetObject".

stati

new

è appena stato creato o aggiornato di recente ma non ancora testato.

valid

ha superato la validazione ed è pronto per essere utilizzato. Un'organizzazione deve avere almeno una configurazione di archiviazione in questo stato per poter essere utilizzata.

invalid

ha fallito il test di validazione. Deve essere aggiornato o ritestato.

deactivated

è stato disattivato dall'organizzazione proprietaria.

changelog

2020/02/27

• Aggiunge il supporto per gli URL firmati. In questo modo viene aggiunto signed_urls_enabled e signed_urls_expiry sull'oggetto di configurazione della memoria per attivare / disattivare la generazione di URL firmati per i risultati e per quanto tempo devono rimanere attivi gli URL firmati.

Crea POST /configs/storage

Quando viene creata una nuova configurazione di archiviazione, l'API tenterà di testarla creando un'attività storage_config.test . Questo compito pubblicherà semplicemente un payload di prova di piccole dimensioni utilizzando la configurazione, che può essere successivamente cancellata. Se l'operazione ha esito positivo, lo stato della configurazione è impostato su valid e diventa utilizzabile con i sondaggi. In caso di errore, lo stato della configurazione sarà impostato su invalid , ma questo può essere riesaminato facilmente utilizzando l' azione di test .

La prima configurazione di archiviazione valida all'interno di un'organizzazione verrà automaticamente impostata come predefinita dell'organizzazione.

Si noti che la creazione delle configurazioni di archiviazione è deduplicata sull'attributo url . Pertanto, non è possibile creare due configurazioni di archiviazione con lo stesso url ma credentials diverse.

parametri

Utilizzando cURL

Qui, il contenuto del dizionario delle credenziali deriva dalla copia dei contenuti del file delle credenziali JSON generato durante l'impostazione dell'account del servizio Google Cloud.

curl https://ricloud-api.reincubate.com/configs/storage \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "gs://my-storage-bucket",
  "credentials": {
      "type": "service_account",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "client_id": "<Google Cloud Platform client ID>",
      "token_uri": "https://oauth2.googleapis.com/token",
      "project_id": "<Google Cloud Platform project ID>",
      "private_key": "<Service Account private key>",
      "client_email": "<Service Account ID>.iam.gserviceaccount.com",
      "private_key_id": "<Service Account private key ID>",
      "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/<Service Account ID>.iam.gserviceaccount.com",
      "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs"
  }
}'

Usando ricloud-py

import json
import ricloud

with open("<path to JSON file>", 'r') as credentials_file:
    credentials = json.load(credentials_file)

storage_config = ricloud.StorageConfig.create(
    url='gs://my-storage-bucket',
    credentials=credentials
)

Recupera GET /configs/storage/{storage_config ID}

Utilizzando cURL

curl https://ricloud-api.reincubate.com/configs/storage/<storage_config ID> \
  -H 'Authorization: Token <your key_token>'

Usando ricloud-py

import ricloud

storage_config = ricloud.StorageConfig.retrieve(<storage_config ID>)

Elenco GET /configs/storage

Le configurazioni di archiviazione nello stato deactivated sono nascoste per impostazione predefinita e possono essere elencate solo mediante filtraggio esplicito.

parametri

Utilizzando cURL

curl https://ricloud-api.reincubate.com/configs/storage \
  -H 'Authorization: Token <your key_token>'

Usando ricloud-py

import ricloud

storage_configs = ricloud.StorageConfig.list()

Aggiorna POST /configs/storage/{storage_config ID}

Questa azione crea un'attività di storage_config.test per verificare la validità di eventuali modifiche apportate alla configurazione.

parametri

Utilizzando cURL

curl https://ricloud-api.reincubate.com/configs/storage/<storage_config ID> \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "gs://my-storage-bucket/subfolder"
}'

Usando ricloud-py

import ricloud

storage_config = ricloud.StorageConfig.update_with_id(
  <storage_config ID>, url="gs://my-storage-bucket/subfolder"
)

# OR

storage_config = ricloud.StorageConfig.retrieve(<storage_config ID>)

storage_config.update(url='gs://my-storage-bucket/subfolder')

Elimina DELETE /configs/storage/{storage_config ID}

Elimina completamente la configurazione di archiviazione dall'API. Ciò rimuove qualsiasi informazione relativa alle credenziali memorizzata nell'API.

Utilizzando cURL

curl https://ricloud-api.reincubate.com/configs/storage/<storage_config ID> \
  -X DELETE \
  -H 'Authorization: Token <your key_token>'

Usando ricloud-py

Dal momento che ricloud-py v3.0.0 .

import ricloud

ricloud.StorageConfig.delete_with_id(<storage_config ID>)

# OR

storage_config = ricloud.StorageConfig.retrieve(<storage_config ID>)

storage_config.delete()

Test POST /configs/storage/{storage_config ID}/test

Questa azione consente di verificare nuovamente la validità di una configurazione di archiviazione. Lo stato della configurazione sarà impostato su valid o invalid base all'esito del test.

Si noti che questa azione restituisce una risorsa di attività.

Utilizzando cURL

curl https://ricloud-api.reincubate.com/configs/storage/<storage_config ID>/test \
  -H 'Authorization: Token <your key_token>'

Usando ricloud-py

import ricloud

test_task = ricloud.StorageConfig.test_with_id(<storage_config ID>)

# OR

storage_config = ricloud.StorageConfig.retrieve(<storage_config ID>)

test_task = storage_config.test()