Configurações de armazenamento

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

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

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

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

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