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

обновленный более недели назад

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

Атрибуты

название	тип	описание
`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.

Типы

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 .

параметры

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

Использование 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 состоянии по умолчанию скрыты и могут быть перечислены только с помощью явной фильтрации.

параметры

название	тип	описание
`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.

Использование 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 для проверки правильности любых изменений, внесенных в конфигурацию.

параметры

название	тип	описание
`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`.

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

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

Атрибуты

Типы

URL-адрес

полномочия

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

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

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

состояния

Изменения

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

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

Список `GET /configs/storage`

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

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

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

Как мы можем помочь?

Реинкубировать информационный бюллетень

Атрибуты

Типы

URL-адрес

полномочия

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

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

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

состояния

Изменения

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

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

Список GET /configs/storage

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

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

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

Как мы можем помочь?

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

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

Список `GET /configs/storage`

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

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

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