Разработчикам

Slider

Наши SDK позволяют легко и безопасно хранить записи в стране их происхождения.

1

Create an account and get an API key

2

Use the SDK for your language

3

You must use an InCountry SDK to ensure that data is encrypted

Вкладки разработчика

Установка

Рекомендуемый способ установки SDK — pipenv (or pip):

$ pipenv install incountry

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

Чтобы получить доступ к вашим данным в InCountry с помощью Python SDK, вам необходимо создать экземпляр класса Storage.

from incountry import Storage

storage = Storage(
    api_key="string", # Требуется передать в SDK напрямую или в качестве переменной среды INC_API_KEY
    environment_id="string", # Требуется передать в SDK напрямую или в качестве переменной среды INC_ENVIRONMENT_ID
    endpoint="string", # Необязательно Определяет URL API
    encrypt=bool, # Необязательно Если False, шифрование не используется
    debug=bool, # Необязательно Если True, позволяет вести отладку
    secret_key_accessor=accessor, # Экземпляр класса SecretKeyAccessor Используется чтобы получить секрет шифрования
)

api_key и environment_id могут быть получены из панели сайта Incountry.

endpoint определяет URL-адрес API и используется для переопределения адреса по умолчанию.

Вы можете отключить шифрование (не рекомендуется). Установите свойство encrypt как false, если вы хотите это сделать.

Ключ шифрования

secret_key_accessor используется для передачи секрета, используемого для шифрования.

Примечание: несмотря на то, что PBKDF2 используется для генерации криптографически надежного ключа шифрования, вы должны сами убедиться, что используете достаточно надежный пароль.

Вот несколько примеров того, как вы можете использовать SecretKeyAccessor.

# Получаем секрет из переменной
from incountry import SecretKeyAccessor

password = "password"
secret_key_accessor = SecretKeyAccessor(lambda: password)

# Получаем секрет через http-запрос
from incountry import SecretKeyAccessor
import requests as req

def get_secret():
 url = "<your_secret_url>"
 r = req.get(url)
    return r.json().get("secret") # при условии, что ответ {"secret": "password"}

secret_key_accessor = SecretKeyAccessor(get_secret)

Запись данных в хранилище

Используйте метод write для создания записи.

record = storage.write(
    country="string", # Обязательный код страны для хранения данных
    key="string", # Обязательный ключ записи
    body="string", #Дополнительные данные
    profile_key="string", # Необязательно
    range_key=integer, # Необязательно
    key2="string", # Необязательно
    key3="string", # Необязательно
)

# `write` возвращает созданную запись в случае успеха

Шифрование

InCountry использует шифрование на стороне клиента для ваших данных. Обратите внимание, что только параметр body зашифрован. Некоторые другие поля хешируются. Вот как данные преобразуются и хранятся в базе данных InCountry:

{
 key, # хэш
 body, # зашифрованный
 profile_key, # хэш
 range_key, # незашифрованный
 key2, # хэш
 key3, # хэш
}

Чтение сохраненных данных

Сохраненную запись можно прочитать используя key с помощью метода readAsync. Он принимает объект с двумя полями: country and key

record = storage.read(
    country="string", # Обязательный код страны для хранения данных
    key="string", # Обязательный ключ записи
)

Поиск записей

Поиск по произвольным ключам возможен с помощью метода find.

records = storage.find(country, limit, offset, **filter_kwargs)

Параметры: country — код страны, limit — максимальное количество записей, которые вы хотели бы получить. По умолчанию 100, offset — указывает количество пропускаемых записей, filter_kwargs — параметры фильтрации

Вот пример того, как можно использовать метод find:

records = storage.find(country="us", limit=10, offset=10, key2="kitty", key3=["mew", "purr"])

Этот вызов возвращает все записи с key2 равным kitty и key3 равным mew или purr. Параметр options определяет количество возвращаемых записей и начальный индекс. Он может быть использован для пагинации. Примечание: SDK возвращает максимум 100 записей.

Возвращаемый объект выглядит следующим образом:

 {
    "data": [...],
    "meta": {
        "limit": 10,
        "offset": 10,
        "total": 124, # общее количество найденных записей, с игнором лимита
 }
 }

Вы можете использовать следующие типы параметров фильтрации. Одно значение:

key2="kitty"

Одно из значений:

key3=["mew", "purr"]

range_key является числовым полем, поэтому вы можете использовать фильтрацию диапазоном, например:

range_key={"$lt": 1000} # поиск записей с помощью range_key < 1000

Доступные варианты для range_key: $lt, $lte, $gt, $gte.

Вы можете искать по любым ключам: key, key2, key3, profile_key, range_key.

Найти одну запись по фильтру

Если вам нужно найти только первую запись, соответсвующую фильтру, то вы можете использовать метод find_one.

record = storage.find_one(country, offset, **filter_kwargs)

Если запись не найдена, он вернёт None.

Удаление записей

Используйте метод deleteAsync, чтобы удалить запись из хранилища InCountry. Это возможно только с помощью поля key.

storage.delete(
    country="string", # Обязательный код страны для хранения данных
    key="string", # Обязательный ключ записи
)

# `delete` вызовет Exception в случае неудачи

Локальное тестирование

  1. В терминале запустите pipenv run tests для юнит-тестов
  2. В терминале запустите pipenv run integrations для интеграционных тестов

Установка

SDK доступен через NPM:

npm install incountry --save

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

Чтобы получить доступ к вашим данным в InCountry с помощью NodeJS SDK, вам необходимо создать экземпляр класса Storage.

const Storage= require('incountry/storage');
const storage = new Storage({
    apiKey="string", // Требуется передать в SDK напрямую или в качестве переменной среды INC_API_KEY
    environmentId="string", // Требуется передать в SDK напрямую или в качестве переменной среды INC_ENVIRONMENT_ID
    endpoint="string", // Необязательно. Определяет URL API
    encrypt=string, // Необязательно. Если False, шифрование не используется
},
    secretKeyAccessor               // Экземпляр класса SecretKeyAccessor. Используется чтобы получить секрет шифрования
    logger                          // Позволяет вести лог на разных уровнях логирование в согласованном порядке
);

apiKey а environmentId можно получить с вашей панели на сайте Incountry.

endpoint определяет URL-адрес API и используется для переопределения адреса по умолчанию.

Вы можете отключить шифрование (не рекомендуется). Установите свойство encrypt как false, если вы хотите это сделать.

Ключ шифрования

secretKeyAccessor используется для передачи секрета, используемого для шифрования.

Примечание: несмотря на то, что PBKDF2 используется для генерации криптографически надежного ключа шифрования, вы должны сами убедиться, что используете достаточно надежный пароль.

Вот несколько примеров того, как вы можете использовать SecretKeyAccessor.

const SecretKeyAccessor = require('incountry/secret-key-accessor');
const secretKeyAccessor = new SecretKeyAccessor(() => {
 return 'longAndStrongPassword'
});

// Asynchronous accessor
const secretKeyAccessor = new SecretKeyAccessor(async () => {
 const password = await getPasswordFromSomewhere();
 return password;
});

// Using promises
const secretKeyAccessor = new SecretKeyAccessor(() => new Promise((resolve) => {
 getPasswordFromSomewhere().then(resolve);
}));

Logging

По умолчанию SDK выводит логи в console в JSON-формате. Вы можете переопределить это поведение, передавая объект logger. Объект logger должен выглядеть следующим образом:

const customLogger = {
write: (logLevel, message) => {}
};

Запись данных в хранилище

Используйте метод writeAsync чтобы создать / перезаписать запись для данного key.

const writeResponse = await storage.writeAsync({
 country: 'string', # Обязательный код страны для хранения данных
 key: 'string', # Обязательный ключ записи
 body: 'string', # Дополнительные данные
 profile_key: 'string', # Необязательно
 range_key: integer, # Необязательно
 key2: 'string', # Необязательно
 key3: 'string', # Необязательно
}

Шифрование

InCountry использует шифрование на стороне клиента для ваших данных. Обратите внимание, что только параметр body зашифрован. Некоторые другие поля хешируются. Вот как данные преобразуются и хранятся в базе данных InCountry:

{
 key, # хэш
 body, # зашифрованный
 profile_key, # хэш
 range_key, # незашифрованный
 key2, # хэш
 key3, # хэш
}

Чтение сохраненных данных

Сохраненную запись можно прочитать используя key с помощью метода readAsync. Он принимает объект с двумя полями: country and key

const readResponse = await storage.readAsync({
    country:"string", # Обязательный код страны для хранения данных
    key:"string", # Обязательный ключ записи
)

// Используйте readResponse.status для кода состояния и readResponse.data для полученной payload.

Обратите внимание, что readAsync возвращает Promise который всегда выполняется. Используйте свойство status для проверки прошла ли операция успешно или нет.

Поиск записей

Поиск по произвольным ключам возможен с помощью метода find.

const records = await storage.find(country, filter, options);

Параметры: country — код страны, filter — фильтр (см. ниже), options — объект, содержащий параметры поиска.

Вот пример того, как можно использовать метод find:

const records = await storage.find('us', {
key2: 'kitty',
key3: ['mew', 'purr'],
}, {
limit: 10,
offset: 10
});

Этот вызов возвращает все записи с key2 равным kitty и key3 равным mew или purr. Параметр options определяет количество возвращаемых записей и начальный индекс. Он может быть использован для пагинации. Примечание: SDK возвращает максимум 100 записей.

Возвращаемый объект выглядит следующим образом:

{
data: [/* kitties */],
meta: {
limit: 10,
offset: 10,
total: 124 // total records matching filter, ignoring limit
}
}

Вы можете использовать следующие типы параметров фильтрации. Одно значение:

{
key2: 'kitty'
}

Одно из значений:

{
key3: ['mew', 'purr']
}

range_key является числовым полем, поэтому вы можете использовать фильтрацию диапазоном, например:

{
range_key: { $lt: 1000 } // search for records with range_key <1000
}

Доступные варианты для range_key: $lt, $lte, $gt, $gte. Вы можете искать по любым ключам: key, key2, key3, profile_key, range_key.

Найти одну запись по фильтру

Если вам нужно найти только первую запись, соответсвующую фильтру, то вы можете использовать метод findOne.

const record = await storage.findOne(country, filter);

Если запись не найдена, он вернёт null.

Удаление записей

Используйте метод deleteAsync, чтобы удалить запись из хранилища InCountry. Это возможно только с помощью поля key.

const deleteResponse = await storage.deleteAsync({
country: 'string',      // Required country code
key: 'string'           // Required record key
});

// Use deleteResponse.status for status code.

Logging

Вы можете указать собственный logger в любое время следующим образом:

const logger = {
 write: (level, message) => { console.log(`[${level}] ${message}`) }
}

storage.setLogger(logger);

Logger должен быть объектом, реализующим метод write, который имеет следующую сигнатуру:

write(level, message)
  • level (string) — message level: DEBUG, INFO, etc.
  • message (string) — log message

Локальное тестирование

  1. В терминале запустите npm run test для юнит-тестов
  2. В терминале запустите npm run integrations для интеграционных тестов

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

Чтобы получить доступ к вашим данным в InCountry с помощью Java SDK, вам необходимо создать экземпляр класса Storage.

 Storage(
 String environmentID,
 String apiKey,
 String endpoint,
 boolean encrypt,
 ISecretKeyAccessor secretKeyAccessor
)

# `write` возвращает созданную запись в случае успеха

apiKey а environmentID можно получить с вашей панели на сайте Incountry.

endpoint определяет URL-адрес API и используется для переопределения адреса по умолчанию.

Вы можете отключить шифрование (не рекомендуется). Установите параметр encrypt как false если вы хотите это сделать.

Ключ шифрования

secretKeyAccessor используется для передачи секрета, используемого для шифрования.

Примечание: несмотря на то, что PBKDF2 используется для генерации криптографически надежного ключа шифрования, вы должны сами убедиться, что используете достаточно надежный пароль.

Вот несколько примеров того, как вы можете использовать SecretKeyAccessor.

public class SimpleSecretKeyAccessor implements ISecretKeyAccessor {
 private String secret;
 public SecretKeyAccessor(String secret) {
 this.secret = secret;
} 
 @Override
 public String getKey() {
 return this.secret;
}
}
SimpleSecretKeyAccessor accessor = new SimpleSecretKeyAccessor("myStrongPassword");

Запись данных в хранилище

Используйте метод write чтобы создать / перезаписать запись для данного key.

public void write(Record record) throws StorageException, GeneralSecurityException, IOException

Как инициализировать объект записи:

public Record(
 String country, # Обязательный код страны для хранения данных
 String key, # Обязательный ключ записи
 String body, # Дополнительные данные
 String profileKey, # Необязательно
 Integer rangeKey, # Необязательно
 String key2, # Необязательно
 String key3, # Необязательно
)

Шифрование

InCountry использует шифрование на стороне клиента для ваших данных. Обратите внимание, что только параметр body зашифрован. Некоторые другие поля хешируются.
Вот как данные преобразуются и хранятся в базе данных InCountry:

{
 key, # хэш
 body, # зашифрованный
 profile_key, # хэш
 range_key, # незашифрованный
 key2, # хэш
 key3, # хэш
}

Чтение сохраненных данных

Stored record can be read by key using read method.

public Record read(String country, String key) throws StorageException, IOException, GeneralSecurityException

country это код страны записи
key это ключ записи

Этот метод возвращает объект Record. Он содержит следующие атрибуты: country, key, body, key2, key3, profileKey, rangeKey.

Эти атрибуты могут быть доступны с помощью getters, например:

String key2 = record.getKey2();
String body = record.getBody();

Поиск записей

Поиск по произвольным ключам возможен с помощью метода find.

public BatchRecord find(String country, FindFilter filter, FindOptions options) throws StorageException, IOException, GeneralSecurityException

Параметры:
country — код страны,
filter — фильтр (см. ниже),
options — объект, содержащий параметры поиска.

FindFilter имеет следующую сигнатуру:

public FindFilter(FilterStringParam key, FilterStringParam profileKey, FilterRangeParam rangeKey, FilterStringParam key2, FilterStringParam key3)

And for FindOptions:

public FindOptions(int limit, int offset) throws FindOptionsException

Существует два разных типа параметров фильтра: FilterStringParam и FilterRangeParam.
FilterStringParam используется для всех ключей, кроме rangeKey:

public FilterStringParam(String[] value);

или

public FilterStringParam(String value);

Вот пример того, как можно использовать метод find:

FindFilter filter = new FindFilter(
 null,
 null,
 null,
 new FilterStringParam("kitty"),
 new FilterStringParam(new String[]{"mew", "pur"})
);

FindOptions options = new FindOptions(10, 10);

BatchRecord records = storage.find("us", filter, options);

Этот вызов возвращает все записи с key2 равным kitty и key3 равным mew или purr.
Примечание: SDK возвращает максимум 100 записей. Используйте пагинацию для перебора всех записей.

Find возвращает объект BatchRecord, который содержит массив из Record и некоторые метаданные:

int count;
int limit;
int offset;
int total;
Record[] records;

Эти атрибуты могут быть доступны с помощью getters, например:

int limit = records.getTotal();

FilterRangeParam работает иначе, чем FilterStringParam. rangeKey — это целое незашифрованное поле, поэтому вы можете выполнять над ним операции диапазона.
Например, вы можете запросить все записи с rangeKey менее 1000:

FilterRangeParam rangeParam = new FilterRangeParam("$lt", 1000);

или если вы хотите просто проверить равенство:

FilterRangeParam rangeParam = new FilterRangeParam(1000);

Доступные варианты для FilterRangeParam: $lt, $lte, $gt, $gte.

Найти одну запись по фильтру

Если вам нужно найти только первую запись, соответсвующую фильтру, то вы можете использовать метод findOne.
Он работает так же, как find, но возвращает первую запись или null, если нет соответствующих записей.

Удаление записей

Use delete method in order to delete a record from InCountry storage. Это возможно только с помощью поля key.

public void delete(String country, String key) throws StorageException, IOException

Здесь country — код страны записи, key — ключ записи