Configuraciones de almacenamiento

Actualizado hace más de una semana

El recurso de configuración de almacenamiento describe dónde la API puede almacenar los datos que pertenecen a los resultados de las encuestas. Todas las ubicaciones especificadas en las configuraciones de almacenamiento deben ser un grupo de almacenamiento en la nube en Google Cloud Storage o Amazon S3 (AWS) .

Atributos

nombre	escribe	descripción
`id`	storage config ID	Resource identifier.
`resource`	string, always `storage_config`	Resource type specifier.
`organisation`	organisation ID	The organisation the resource belongs to.
`type`	string	One of: `gs`, `s3`. This is a read-only attribute generated from the `url`.
`url`	string	A URL representing the target to which results will be published.
`credentials`	dictionary	A dictionary containing the credential information used by the API to authenticate against the storage service.
`signed_urls_enabled`	optional bool, default false	Whether signed URLs should be generated for results published using the storage config.
`signed_urls_expiry`	optional timedelta	If signed URLs are enabled, the time, in seconds, they will remain valid.
`state`	string	One of: `'new'`, `'valid'`, `'invalid'`, `'deactivated'`.
`date_created`	datetime	When the resource was created.

Los tipos

gs: el tipo de configuración de almacenamiento de Google Cloud Storage . Requiere credenciales de cuenta de servicio.
s3: El tipo de configuración de almacenamiento de Amazon S3 (AWS) . Requiere credenciales de usuario de AWS.

URLs

El atributo url sigue el formato:

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

Por ejemplo, dado que tenemos un grupo en Google Cloud Storage con el nombre 'my-bucket' y queremos que la API se publique en una carpeta dentro de este grupo llamada 'resultados', la url se vería así:

gs://my-bucket/results

Cartas credenciales

Credenciales de almacenamiento en la nube de Google

La API espera que el atributo de credentials sea un diccionario con el 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"
}

Esto coincide exactamente con el archivo JSON de salida al crear una clave de cuenta de servicio a través de la consola de Google Cloud Platform.

Para simplificar la configuración de una configuración de almacenamiento utilizando las credenciales de archivo JSON exportadas, ricloud-py incluye un simple comando cli:

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

Credenciales de Amazon S3

La API esperaba que el atributo de credentials fuera un diccionario con el formato:

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

En la carga útil de credenciales anterior, el parámetro user_name corresponde al nombre de usuario del usuario de AWS IAM al que pertenece la clave de acceso. Esto puede ser útil para incluir con fines administrativos y de auditoría.

Esto se puede construir manualmente desde los detalles que se muestran en la consola de AWS, o desde el archivo CSV exportable a través del comando cli de ricloud-py :

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

URL firmadas

Las URL firmadas son enlaces preautorizados de tiempo limitado para acceder a un elemento en un depósito de almacenamiento en la nube. Permiten que las implementaciones den acceso seguro a un elemento específico al que el cliente no tendría credenciales para acceder, o ninguna credencial.

Cuando URL firmados están habilitados en una configuración de almacenamiento, cualquier resultado publicada el uso que tendrá la configuración signed_url poblar atributo. Ver atributos de resultados para más detalles.

Las URL firmadas son compatibles con Google Cloud Storage ( enlace a documentos de URL firmadas de GCS ) y AWS S3 ( enlace a documentos S3 ).

Un requisito adicional para las URL firmadas es que el usuario asociado con las credenciales de configuración de almacenamiento debe tener permisos de lectura en los objetos del depósito. En GCS esta es la función "Visor de objetos de almacenamiento". En S3 está la acción de política "s3: GetObject".

Estados

new: se acaba de crear o actualizar recientemente, pero aún no se ha probado.
valid: Ha pasado la validación y está listo para ser utilizado. Una organización debe tener al menos una configuración de almacenamiento en este estado para poder ser utilizada.
invalid: Ha fallado la prueba de validación. Debe ser actualizado o reexaminado.
deactivated: ha sido desactivado por la organización propietaria.

Registro de cambios

2020-02-27

Agrega soporte para URL firmadas. Esto agrega el signed_urls_enabled signed_urls_expiry en el objeto de configuración de almacenamiento para alternar la generación de URL firmadas para obtener resultados y cuánto tiempo deben estar activas las URL firmadas.

Crear `POST /configs/storage`

Cuando se crea una nueva configuración de almacenamiento, la API intentará probarlo creando una tarea storage_config.test . Esta tarea simplemente publicará una pequeña carga útil de prueba utilizando la configuración, que luego se puede eliminar de forma segura. Si la operación se realiza correctamente, el estado de la configuración se establece como valid y se puede utilizar con encuestas. En caso de fallo, el estado de la configuración se establecerá como invalid , pero esto se puede volver a probar fácilmente mediante la acción de prueba .

La primera configuración de almacenamiento válida dentro de una organización se establecerá automáticamente como la predeterminada de la organización.

Tenga en cuenta que la creación de configuraciones de almacenamiento se deduplica en el atributo url . Por lo tanto, no es posible crear dos configuraciones de almacenamiento con la misma url pero diferentes credentials .

Parámetros

name	type	description
`url`	required	The storage configuration URL for your bucket.
`credentials`	required	The storage configuration credentials for your bucket.

Usando cURL

Aquí, el contenido del diccionario de credenciales proviene de la copia del contenido del archivo de credenciales JSON generado durante la configuración de la cuenta de servicio en la nube de Google.

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"
  }
}'

Utilizando 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
)

Recuperar `GET /configs/storage/{storage_config ID}`

Usando cURL

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

Utilizando ricloud-py

import ricloud

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

Lista `GET /configs/storage`

Las configuraciones de almacenamiento en el estado deactivated están ocultas por defecto y solo se pueden listar por filtrado explícito.

Parámetros

nombre	escribe	descripción
`type`	string	Filter by backing bucket's type.
`state`	string	Filter by the configuration's state.
`date_created`	datetime filter	Filter by resouce creation date.

Usando cURL

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

Utilizando ricloud-py

import ricloud

storage_configs = ricloud.StorageConfig.list()

Actualizar `POST /configs/storage/{storage_config ID}`

Esta acción crea una tarea storage_config.test para verificar la validez de cualquier cambio realizado en la configuración.

Parámetros

nombre	escribe	descripción
`url`	string	Update the URL to point to a different bucket or location within the bucket. Note that the type of a bucket cannot be changed through this operation.
`credentials`	dictionary	Update the credentials.
`state`	string	Only to `new` or `deactivated`.

Usando 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"
}'

Utilizando 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')

Eliminar `DELETE /configs/storage/{storage_config ID}`

Borra la configuración de almacenamiento de la API por completo. Esto elimina cualquier información de credenciales relacionada almacenada en la API.

Usando cURL

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

Utilizando ricloud-py

Desde 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()

Prueba `POST /configs/storage/{storage_config ID}/test`

Esta acción le permite volver a probar la validez de una configuración de almacenamiento. El estado de la configuración se establecerá en valid o invalid según el resultado de la prueba.

Tenga en cuenta que esta acción devuelve un recurso de tarea.

Usando cURL

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

Utilizando 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()

Configuraciones de almacenamiento

Atributos

Los tipos

URLs

Cartas credenciales

Credenciales de almacenamiento en la nube de Google

Credenciales de Amazon S3

URL firmadas

Estados

Registro de cambios

Crear `POST /configs/storage`

Recuperar `GET /configs/storage/{storage_config ID}`

Lista `GET /configs/storage`

Actualizar `POST /configs/storage/{storage_config ID}`

Eliminar `DELETE /configs/storage/{storage_config ID}`

Prueba `POST /configs/storage/{storage_config ID}/test`

¿Cómo podemos ayudar?

Boletín Reincubar

Atributos

Los tipos

URLs

Cartas credenciales

Credenciales de almacenamiento en la nube de Google

Credenciales de Amazon S3

URL firmadas

Estados

Registro de cambios

Crear POST /configs/storage

Recuperar GET /configs/storage/{storage_config ID}

Lista GET /configs/storage

Actualizar POST /configs/storage/{storage_config ID}

Eliminar DELETE /configs/storage/{storage_config ID}

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

¿Cómo podemos ayudar?

Crear `POST /configs/storage`

Recuperar `GET /configs/storage/{storage_config ID}`

Lista `GET /configs/storage`

Actualizar `POST /configs/storage/{storage_config ID}`

Eliminar `DELETE /configs/storage/{storage_config ID}`

Prueba `POST /configs/storage/{storage_config ID}/test`