Конфиги хранения

Ресурс конфигурации хранилища описывает, где API может хранить данные, относящиеся к результатам опросов. Все местоположения, указанные в конфигах хранилища, должны быть облачным хранилищем либо в Google Cloud Storage, либо в Amazon S3 (AWS) .

Атрибуты

Типы

gs

тип конфигурации хранилища Google Cloud Storage . Требуются учетные данные учетной записи службы.

s3

тип конфигурации хранилища Amazon S3 (AWS) . Требуются учетные данные пользователя AWS.

URL-адрес

Атрибут url соответствует формату:

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

Например, если у нас есть хранилище в облачном хранилище Google с именем «my-bucket», и мы хотим, чтобы API-интерфейс публиковал в папке внутри этого сегмента с именем «results», url будет выглядеть следующим образом:

gs://my-bucket/results

полномочия

Учетные данные Google Cloud Storage

API ожидает, что атрибут 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"
}

Это точно соответствует выходному файлу JSON при создании ключа учетной записи службы через консоль Google Cloud Platform.

Чтобы упростить настройку конфигурации хранилища с использованием экспортированных учетных данных файла JSON, ricloud-py включает в себя простую команду cli:

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

Учетные данные Amazon S3

API ожидал, что атрибутом credentials будет словарь в формате:

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

В описанной выше полезной нагрузке параметр user_name соответствует имени пользователя AWS IAM, которому принадлежит ключ доступа. Это может быть полезно включить в административных и аудиторских целях.

Это можно создать вручную из деталей, показанных в консоли AWS, или из экспортируемого файла CSV с помощью команды cli ricloud-py

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

Подписанные URL

Подписанные URL-адреса представляют собой ограниченные по времени предварительно авторизованные ссылки для доступа к элементу в корзине облачного хранилища. Они позволяют реализациям предоставлять безопасный доступ к определенному элементу, который в противном случае клиент не имел бы для доступа или не имел учетных данных.

Когда подписанные URL-адреса включены в конфигурации хранилища, любой результат, опубликованный с использованием этой конфигурации, будет signed_url атрибутом signed_url . Смотрите атрибуты результата для более подробной информации.

Подписанные URL-адреса поддерживаются как Google Cloud Storage ( ссылка на документы с подписанными URL-адресами GCS ), так и AWS S3 ( ссылка на документы S3 ).

Одно дополнительное требование для подписанных URL-адресов заключается в том, что пользователь, связанный с учетными данными конфигурации хранилища, должен иметь разрешения на чтение для объектов в корзине. В GCS это роль «Просмотр объекта хранилища». В S3 это действие политики "s3: GetObject".

состояния

new

только что был создан или недавно обновлен, но еще не протестирован.

valid

прошел проверку и готов к использованию. Организация должна иметь хотя бы одну конфигурацию хранилища в этом состоянии, чтобы ее можно было использовать.

invalid

не прошел валидационный тест Должен быть обновлен или проверен.

deactivated

была отключена организацией-владельцем.

Изменения

2020-02-27

• Добавлена поддержка подписанных URL-адресов. При этом в signed_urls_enabled конфигурации хранилища добавляются signed_urls_enabled и signed_urls_expiry signed_urls_enabled и signed_urls_expiry чтобы переключать генерацию подписанных URL-адресов для результатов и продолжительность активности подписанных URL-адресов.

Создать POST /configs/storage

При создании новой конфигурации хранилища API попытается проверить ее, создав задачу storage_config.test . Эта задача просто опубликует небольшую тестовую полезную нагрузку, используя конфигурацию, которую впоследствии можно будет безопасно удалить. Если операция завершается успешно, состояние конфига устанавливается на valid и становится полезным для использования с опросами. В случае сбоя состояние конфига будет установлено как invalid , но это можно легко повторно протестировать с помощью действия теста .

Первая допустимая конфигурация хранилища в организации будет автоматически установлена по умолчанию для организации.

Обратите внимание, что создание конфигов хранилища дедуплицируется в атрибуте url . Поэтому невозможно создать две конфигурации хранилища с одинаковыми url но разными credentials .

параметры

Использование cURL

Здесь содержимое словаря учетных данных получается путем копирования содержимого файла учетных данных JSON, созданного при настройке учетной записи облачной службы 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"
  }
}'

Использование 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
)

Получить GET /configs/storage/{storage_config ID}

Использование cURL

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

Использование ricloud-py

import ricloud

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

Список GET /configs/storage

Конфиги хранилища в deactivated состоянии по умолчанию скрыты и могут быть перечислены только с помощью явной фильтрации.

параметры

Использование cURL

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

Использование ricloud-py

import ricloud

storage_configs = ricloud.StorageConfig.list()

Обновить POST /configs/storage/{storage_config ID}

Это действие создает задачу storage_config.test для проверки правильности любых изменений, внесенных в конфигурацию.

параметры

Использование 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"
}'

Использование 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')

Удалить DELETE /configs/storage/{storage_config ID}

Полностью удаляет конфигурацию хранилища из API. Это удаляет любую связанную учетную информацию, хранящуюся в API.

Использование cURL

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

Использование ricloud-py

Начиная с 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()

Тест POST /configs/storage/{storage_config ID}/test

Это действие позволяет повторно проверить правильность конфигурации хранилища. Состояние конфигурации будет установлено как valid или invalid зависимости от результатов теста.

Обратите внимание, что это действие возвращает ресурс задачи.

Использование cURL

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

Использование 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()