Configurações de armazenamento

Atualizada mais de uma semana atras

O recurso de configuração de armazenamento descreve onde a API pode armazenar os dados pertencentes aos resultados das pesquisas. Todos os locais especificados nas configurações de armazenamento devem ser um repositório de armazenamento em nuvem no Google Cloud Storage ou no Amazon S3 (AWS) .

Atributos

nome	modelo	Descrição
`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.

Tipos

gs: o tipo de configuração de armazenamento do Google Cloud Storage . Requer credenciais da conta de serviço.
s3: o tipo de configuração de armazenamento do Amazon S3 (AWS) . Requer credenciais de usuário da AWS.

URLs

O atributo url segue o formato:

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

Por exemplo, dado que temos um intervalo no Google Cloud Storage com o nome "my-bucket" e queremos que a API publique em uma pasta desse intervalo chamada "results", a url seria:

gs://my-bucket/results

Credenciais

Credenciais do Google Cloud Storage

A API espera que o atributo de credentials seja um dicionário com o 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"
}

Isso corresponde exatamente ao arquivo JSON de saída ao criar uma chave de conta de serviço por meio do console do Google Cloud Platform.

Para simplificar a configuração de uma configuração de armazenamento usando as credenciais de arquivo JSON exportadas, o ricloud-py inclui um comando cli simples:

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

Credenciais do Amazon S3

A API esperava que o atributo de credentials fosse um dicionário com o formato:

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

Na carga útil das credenciais acima, o parâmetro user_name corresponde ao nome de usuário do usuário do AWS IAM ao qual a chave de acesso pertence. Isso pode ser útil para fins administrativos e de auditoria.

Isso pode ser construído manualmente a partir dos detalhes mostrados no console da AWS ou do arquivo CSV exportável através do comando cli do ricloud-py :

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

URLs assinados

URLs assinados são links pré-autorizados e com limite de tempo para acessar um item em um bucket de armazenamento em nuvem. Eles permitem que as implementações dêem acesso seguro a um item específico que, de outra forma, o cliente não teria credenciais para acessar ou nenhuma credencial.

Quando URLs assinados são ativados em uma configuração de armazenamento, qualquer resultado publicado usando essa configuração terá o atributo signed_url preenchido. Consulte os atributos do resultado para obter mais detalhes.

Os URLs assinados são suportados pelo Google Cloud Storage ( link para documentos de URLs assinados pelo GCS ) e pela AWS S3 ( link para documentos do S3 ).

Um requisito adicional para URLs assinados é que o usuário associado às credenciais de configuração de armazenamento tenha permissões de leitura nos objetos no bucket. No GCS, essa é a função "Storage Object Viewer". No S3, está a ação da política "s3: GetObject".

Estados

new: acaba de ser criado ou atualizado recentemente, mas ainda não foi testado.
valid: passou pela validação e está pronto para ser usado. Uma organização deve ter pelo menos uma configuração de armazenamento nesse estado para ser utilizável.
invalid: falhou no teste de validação. Deve ser atualizado ou testado novamente.
deactivated: foi desativado pela organização proprietária.

Changelog

2020-02-27

Adiciona suporte para URLs assinados. Isso adiciona o signed_urls_enabled e o signed_urls_expiry no objeto de configuração de armazenamento para alternar a geração de URLs assinados para obter resultados e por quanto tempo os URLs assinados devem estar ativos.

Criar `POST /configs/storage`

Quando uma nova configuração de armazenamento é criada, a API tentará testá-la criando uma tarefa storage_config.test . Esta tarefa irá simplesmente publicar uma pequena carga de teste usando a configuração, que pode ser deletada com segurança posteriormente. Se a operação for bem-sucedida, o estado da configuração será definido como valid e poderá ser usado com as pesquisas. Em caso de falha, o estado da configuração será definido como invalid , mas isso pode ser testado novamente usando a ação de teste .

A primeira configuração de armazenamento válida dentro de uma organização será automaticamente definida como o padrão da organização.

Observe que a criação de configurações de armazenamento é desduplicada no atributo url . Portanto, não é possível criar duas configurações de armazenamento com o mesmo url mas com credentials diferentes.

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

Aqui, o conteúdo do dicionário de credenciais vem da cópia do conteúdo do arquivo de credenciais JSON gerado durante a configuração da Conta do Google Cloud Service.

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
)

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

Usando ricloud-py

import ricloud

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

Listar `GET /configs/storage`

As configurações de armazenamento no estado deactivated são ocultas por padrão e só podem ser listadas por filtragem explícita.

Parâmetros

nome	modelo	Descrição
`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>'

Usando ricloud-py

import ricloud

storage_configs = ricloud.StorageConfig.list()

Atualizar o `POST /configs/storage/{storage_config ID}`

Essa ação cria uma tarefa storage_config.test para verificar a validade de quaisquer alterações feitas na configuração.

Parâmetros

nome	modelo	Descrição
`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"
}'

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

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

Exclui totalmente a configuração de armazenamento da API. Isso remove as informações de credenciais relacionadas armazenadas na API.

Usando cURL

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

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

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

Esta ação permite que você teste novamente a validade de uma configuração de armazenamento. O estado da configuração será definido como valid ou invalid dependendo do resultado do teste.

Observe que esta ação retorna um recurso de tarefa.

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

Configurações de armazenamento

Atributos

Tipos

URLs

Credenciais

Credenciais do Google Cloud Storage

Credenciais do Amazon S3

URLs assinados

Estados

Changelog

Criar `POST /configs/storage`

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

Listar `GET /configs/storage`

Atualizar o `POST /configs/storage/{storage_config ID}`

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

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

Como podemos ajudar?

Boletim informativo reincubar

Atributos

Tipos

URLs

Credenciais

Credenciais do Google Cloud Storage

Credenciais do Amazon S3

URLs assinados

Estados

Changelog

Criar POST /configs/storage

Recuperar GET /configs/storage/{storage_config ID}

Listar GET /configs/storage

Atualizar o POST /configs/storage/{storage_config ID}

Excluir DELETE /configs/storage/{storage_config ID}

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

Como podemos ajudar?

Criar `POST /configs/storage`

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

Listar `GET /configs/storage`

Atualizar o `POST /configs/storage/{storage_config ID}`

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

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