Configurações de armazenamento

Atualizada
Cover image for: 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

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

Como podemos ajudar?

Nossa equipe de suporte está aqui para ajudar!

Nosso horário de atendimento é de segunda a sexta, das 9h às 17h GMT. A hora é atualmente 4:14 PM GMT.

Nosso objetivo é responder a todas as mensagens dentro de um dia útil.

Nossa equipe de suporte incrível

Podemos melhorar este artigo?

Adoramos ouvir os usuários: por que não nos enviar um e-mail, deixar um comentário ou twittar? @reincubate?

© 2008 - 2023 Reincubate Ltd. Todos os direitos reservados. Registrado na Inglaterra e no País de Gales #5189175, VAT GB151788978. Reincubate® e Camo® são marcas registradas. Política de Privacidade & termos. Construído com em Londres.