开发者

Slider

我们的 SDK 使在所在国存储记录变得简单和安全

1

创建一个帐户并获取一个API密钥

2

使用您熟悉编程语言的SDK

3

您必须使用InCountry SDK
确保数据被加密

开发人员选项卡

安装

安装SDK推荐的方法是使用pipenv(或pip)

$ pipenv install incountry

使用

要使用Python SDK访问InCountry中的数据,您需要创建一个存储类型的实例

from incountry import Storage

storage = Storage(
    api_key="string",                 # Required to be passed in, or as environment variable INC_API_KEY
    environment_id="string",          # Required to be passed in, or as environment variable INC_ENVIRONMENT_ID
    endpoint="string",                # Optional. Defines API URL
    encrypt=bool,                     # Optional. If False, encryption is not used
    debug=bool,                       # Optional. If True enables some debug logging
    secret_key_accessor=accessor,     # Instance of SecretKeyAccessor class. Used to fetch encryption secret
)

api_keyenvironment_id可以在Incountry网站上您的仪表板上获取。

端点定义API URL并用于覆盖默认URL。.

您可以关闭加密(不推荐)。如果要执行此操作,请将加密属性设置为false。

加密密钥

secret_key_accessor 用加密技术传输机密。

请注意: 即使PBKDF2使用在内部生成加密形式的强加密密钥,仍要确保使用高强度密码。

以下是如何使用 SecretKeyAccessor的示例

# Get secret from variable
from incountry import SecretKeyAccessor

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

# Get secret via http request
from incountry import SecretKeyAccessor
import requests as req

def get_secret():
    url = "<your_secret_url>"
    r = req.get(url)
    return r.json().get("secret") # assuming response is {"secret": "password"}

secret_key_accessor = SecretKeyAccessor(get_secret)

将数据写入到存储中

为了创建记录需要使用write方法.

record = storage.write(
    country="string",     # Required country code of where to store the data
    key="string",         # Required record key
    body="string",        # Optional payload
    profile_key="string"# Optional
    range_key=integer,    # Optional
    key2="string",        # Optional
    key3="string",        # Optional
)

# `write` returns created record on success

加密

InCountry对您的数据使用客户端加密. 请注意 只有正文被加密。其他一些字段已经过哈希处理。以下是如何在InCountry数据库中转换和存储数据:

{
    key,           # hashed
    body,          # encrypted
    profile_key,   # hashed
    range_key,     # plain
    key2,          # hashed
    key3,          # hashed
}

读取存储的数据

可以通过使用readAsync方法密钥读取存储的记录。它接受具有两个字段的对象:countrykey

record = storage.read(
    country="string",      # Required country code
    key="string",          # Required record key
)

查找记录

可以使用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,    # 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.

查找一个匹配滤波器的记录

如果需要查找第一个匹配滤波器的记录,可以使用find_one方法。

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

如果没有找到记录,它将返回None.

删除记录

为了从InCountry存储中删除记录使用deleteAsync方法。只能使用密钥字段。

storage.delete(
    country="string",    # Required country code
    key="string",        # Required record key
)

# `delete` will raise an Exception if fails

本地测试

  1. 在终端运行pipenv中针对单元测试进行运行测试
  2. 在终端运行pipenv中运行集成以运行集成测试

安装

SDK可以通过NPM使用

npm install incountry --save

使用

要在InCountry使用NodeJS-SDK访问数据,需要创建一个存储类的实例。

const Storage= require('incountry/storage');
const storage = new Storage({
    apiKey="string",                 // Required to be passed in, or as environment variable INC_API_KEY
    environmentId="string",          // Required to be passed in, or as environment variable INC_ENVIRONMENT_ID
    endpoint="string",               // Optional. Defines API URL
    encrypt=string,                  // Optional. If false, encryption is not used
},
    secretKeyAccessor               // Instance of SecretKeyAccessor class. Used to fetch encryption secret
    logger                          // Allows for logging at different log levels in a consistent manner
);

api_keyenvironment_id可以在Incountry网站上您的仪表板上获取。

端点定义API URL并用于覆盖默认URL。

您可以关闭加密(不推荐)。如果要执行此操作,请将加密属性设置为false

加密密钥

secret_key_accessor 用加密技术传输机密。

请注意: 即使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);
}));

日志记录

在默认情况下, SDK输出以JSON格式登录到控制台。 您可以传递记录器对象覆盖该行为。 记录器对象必须如下内容所示:

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

将数据写入到存储中

需要使用writeAsync方法创建/覆盖给定的密钥的记录.

const writeResponse = await storage.writeAsync({
    country: 'string',       # Required country code of where to store the data
    key: 'string',           # Required record key
    body: 'string',          # Optional payload
    profile_key: 'string',   # Optional
    range_key: integer,      # Optional
    key2: 'string',          # Optional
    key3: 'string',          # Optional
}

加密

InCountry对您的数据使用客户端加密. 请注意 只有正文被加密。其他一些字段已经过哈希处理。以下是如何在InCountry数据库中转换和存储数据:

{
    key,           # hashed
    body,          # encrypted
    profile_key,   # hashed
    range_key,     # plain
    key2,          # hashed
    key3,          # hashed
}

读取存储的数据

可以通过使用readAsync方法密钥读取存储的记录。它接受具有两个字段的对象:countrykey

const readResponse = await storage.readAsync({
    country:"string",      # Required country code
    key:"string",          # Required record key
)

对于状态代码使用readResponse.status,对于收到有效负载使用readResponse.data

请注意,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等于kittykey3等于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.

查找一个匹配滤波器的记录

如果需要查找第一个匹配滤波器的记录,可以使用find_one方法。

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

如果没有找到记录,它将返回null.

删除记录

为了从InCountry存储中删除记录使用deleteAsync方法。只能使用密钥字段。

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

// Use deleteResponse.status for status code.

日志记录

您可以随时指定自定义记录器,如下所示:

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

storage.setLogger(logger);

记录器必须是实现write方法的对象,该方法具有以下签名:

write(level, message)
  • 级别(字符串)-消息级别:DEBUG、INFO等。.
  • 消息(字符串)-日志消息

本地测试

  1. 在终端运行nmp中针对单元测试进行运行测试
  2. 在终端运行nmp中运行集成以运行集成测试

使用

要使用Java SDK访问InCountry中的数据,您需要创建一个存储类型的实例

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

# `write` 返回成功创建的记录

api_keyenvironment_id可以在Incountry网站上您的仪表板上获取。

端点定义API URL并用于覆盖默认URL。

您可以关闭加密(不推荐)。如果要执行此操作,请将加密属性设置为false

加密密钥

secret_key_accessor 用加密技术传输机密。

请注意: 即使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");

将数据写入到存储中

需要使用writeAsync方法创建/覆盖给定的密钥的记录

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

以下是如何初始化记录对象:

public Record(
    String country,       # Required country code of where to store the data
    String key,           # Required record key
    String body,          # Optional payload
    String profileKey,    # Optional
    Integer rangeKey,     # Optional
    String key2,          # Optional
    String key3,          # Optional
)

加密

InCountry对您的数据使用客户端加密. 请注意 只有正文被加密。其他一些字段已经过哈希处理。
以下是如何在InCountry数据库中转换和存储数据:

{
    key,           # hashed
    body,          # encrypted
    profile_key,   # hashed
    range_key,     # plain
    key2,          # hashed
    key3,          # hashed
}

读取存储的数据

可以通过使用readAsync方法密钥读取存储的记录。它接受具有两个字段的对象:

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

国家是记录的国家代码
key是记录密钥

此方法返回记录对象。它包含以下属性:countrykeybodykey2key3profileKeyrangeKey
可以被getters访问这些属性,例如:

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

查找记录

可以使用查找方法通过随机键进行搜索。

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)

对于FindOptions:

public FindOptions(int limit, int offset) throws FindOptionsException

有两种不同类型的过滤器参数:FilterStringParamfilterrageparam
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等于kittykey3等于mewpurr的所有记录。
请注意:SDK最多返回100条记录。使用分页迭代所有记录。

Find返回包含记录数组和一些元数据的BatchRecord对象:

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

查找一个匹配滤波器的记录

如果需要查找第一个匹配滤波器的记录,可以使用find_one方法。
它的工作方式与find相同,但如果没有匹配的记录,则返回第一条记录或null

删除记录

为了从InCountry存储中删除记录使用deleteAsync方法。只能使用密钥字段。

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

以下是country是记录的国家代码, key是记录密钥