المبرمجين

Slider

تجعل رزمة تطوير البرمجيات SDK الخاصة بنا من السهل والأمان تخزين السجلات في بلدها الأصلي

1

أنشئ حسابًا واحصل على مفتاح API

2

استخدم SDK للغة الخاصة بك

3

يجب عليك استخدام InCountry SDK لضمان تشفير البيانات

Developer Tabs

التثبيت

الطريقة الموصى بها لتثبيت SDK هي استخدام pipenv (أو pip):

$ pipenv install incountry

الاستخدام

للوصول إلى بياناتك في إنكنتري باستخدام Python SDK، تحتاج إلى إنشاء مثيل لفئة التخزين.

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_key و environment_id من لوحة التحكم الخاصة بك على موقع إنكنتري.
تحدد نقطة النهاية عنوان API URL وتستخدم لتجاوز أحد عناوين URL الافتراضية.
يمكنك إيقاف التشفير (غير مستحسن). إذا كنت تريد القيام بذلك، غيِّر خاصية التشفير إلى خطأ.

مفتاح التشفير

يتم استخدام مفتاح الدخول السري 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)

كتابة البيانات على التخزين

استخدم أسلوب الكتابة لإنشاء سجل.

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

التشفير

تستخدم إنكنتري تشفير بياناتك من جانب العميل. لاحظ أنه يتم تشفير النص الأساسي فقط. وتتم تجزئة بعض المعلومات الأخرى. وإليك كيفية تحويل البيانات وتخزينها في قاعدة بيانات إنكنتري:

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

قراءة البيانات المخزنة

يمكن قراءة السجل المخزن بواسطة المفتاح باستخدام أسلوب readAsync. فهو يقبل عنصر ذات حقلين: البلد والمفتاح

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

البحث عن السجلات

من الممكن البحث باستخدام مفاتيح عشوائية باستخدام أسلوب البحث.

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

المحددات: البلد – رمز البلد، الحد – الحد الأقصى من السجلات التي ترغب في استردادها. الإعدادات الافتراضية لـ 100، الإزاحة – تحدد عدد السجلات التي يجب تخطيها ، filter_kwargs – محددات الفلتر.

في ما يلي مثال لكيفية استخدام طريقة البحث:

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

ترجع هذه المكالمة جميع السجلات التي تحتوي على key2 يساوي kitty و key3 يساوي mew أو purr. يحدد محدد الخيارات عدد السجلات المراد إرجاعها وفهرس البداية. ويمكن استخدامه لترقيم الصفحات. ملاحظة: تقوم 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)

إذا لم يتم العثور على السجل، فلن يعيد أي منها.

حذف السجلات

استخدم أسلوب deleteAsync لحذف سجل من السجلات المخزنة لدى إنكنتري. من الممكن فقط باستخدام الحقل الرئيسي.

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

# `delete` will raise an Exception if fails

الفحص محليًا

  1. في تشغيل terminal التي تديرها pipenv من أجل اختبارات الوحدة
  2. في terminal تكاملات المحطات التي تديرها 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
);

يمكن جلب apiKey و environmentId من لوحة التحكم الخاصة بك على موقع Incountry.

تحدد نقطة النهاية عنوان API URL وتستخدم لتجاوز أحد العناوين الافتراضية.

يمكنك إيقاف التشفير (غير مستحسن). وإذا كنت تريد القيام بذلك، غيِّر إعداد خاصية التشفير إلى خطأ.

مفتاح التشفير

يتم استخدام مفتاح الدخول السري 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. فهو يقبل عنصر من حقلين: البلد والمفتاح

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

// استخدم readResponse.status لرمز الحالة و readResponse.data للحمولة المستلمة.

لاحظ أن readAsync يعيد وعدًا يتم الوفاء به دائمًا. استخدم خاصية الحالة للتحقق مما إذا تمت العملية بنجاح أم لا.

البحث عن السجلات

من الممكن البحث باستخدام مفاتيح عشوائية باستخدام أسلوب البحث.

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

المعايير: البلد – رمز البلد، الفلتر – عنصر فلتر (انظر أدناه)، خيارات – عنصر يحتوي على خيارات البحث.

في ما يلي مثال حول كيفية استخدام طريقة البحث:

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

يعمل هذا الاتصال على إعادة جميع السجلات التي تحتوي على key2 يساوي kitty و key3 يساوي mew أو purr. ويعمل محدد الخيارات على تحديد عدد السجلات المراد إعادتها وفهرس البداية. ويمكن استخدامه لترقيم الصفحات. ملاحظة: تقوم رزمة تطوير البرمجيات 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
}

خيارات الطلب المتاحة لمفتاح النطاق: lt, $lte, $gt, $gte$. يمكنك البحث بأي من المفاتيح : key، key2 ،key3 ، مفتاح التعريف profile_key : مفتاح النطاقrange_key

ابحث عن واحد “find_one”.

إذا كنت بحاجة إلى العثور على أول سجل مطابق للفلتر، فيمكنك استخدام أسلوب ابحث عن واحد findOne.

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

إذا لم يتم العثور على السجل ، فسيتم إرجاعه فارغًا.

حذف السجلات

استخدم أسلوب deleteAsync لحذف أحد السجلات المخزنة لدى إنكنتري InCountry. وهذا ممكن فقط باستخدام الحقل الرئيسي.

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(level, message)
  • المستوى (السلسلة) – مستوى الرسالة: DEBUG ،INFO ، إلخ.
  • رسالة (سلسلة) – رسالة تسجيل

الاختبار محليًا

  1. عند التشغيل الطرفي يعمل مدير رزمة نود npm على إدارة الاختبار من اجل اختبارات الوحدة
  2. عند التشغيل الطرفي يعمل مدير رزمة نود npm على إدارة التكاملات من أجل القيام باختبارات التكامل

الاستخدام

للوصول إلى بياناتك في InCountry باستخدام رزمة تطوير برمجيات جافا Java SDK، تحتاج إلى إنشاء مثيل لفئة التخزين.

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

# ‘write’ تعيد السجل الذي تم إنشاؤه بنجاح

يمكن جلب apiKey و environmentID من لوحة التحكم الخاصة بك على موقع Incountry.

تحدد نقطة النهاية عنوان API URL وتستخدم لتجاوز أحد العناوين الافتراضية.

يمكنك إيقاف التشفير (غير مستحسن). وإذا كنت تريد القيام بذلك، غيِّر إعداد خاصية التشفير إلى خطأ.

مفتاح التشفير

يتم استخدام مفتاح الدخول السري 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");

كتابة البيانات على التخزين

استخدم اسلوب الكتابة write method لإنشاء /استبدال سجِّل لمفتاح معين.

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 تشفير بياناتك من جانب العميل. لاحظ أنه يتم تشفير النص الأساسي فقط. وتتم تجزئة بعض المعلومات الأخرى:

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

قراءة البيانات المخزنة

من الممكن قراءة السجل باستخدام مفاتيح أسلوب اقرأ.

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

البلد هو رمز بلد السجل
المفتاح هو مفتاح السجل

يعيد هذا الأسلوبعنصر التسجيل. وهو يحتوي على الخصائص التالية: country, key, body, key2, key3, profileKey, rangeKey

يمكن الوصول إلى هذه الخصائص باستخدام ادوات قراءة القيم 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

هناك نوعان مختلفان من معايير الفلترة: FilterStringParam و FilterRangeParam.
يستخدم FilterStringParam لجميع المفاتيح باستثناء مفتلح النطاق ramge-key:

public FilterStringParam(String[] value);

أو

public FilterStringParam(String value);

في ما يلي مثال لكيفية استخدام أسلوب البحث:

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 OR purr.
ملاحظة: تقوم رزمة تطوير البرمجيات SDK بإعادة 100 سجل على الأكثر. استخدم ترقيم الصفحات لتكراره في جميع السجلات.

يقوم Find بإعادة عنصر BatchRecord الذي يحتوي على مصفوفة من السجل وبعض البيانات الوصفية metadata:

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

يمكن الوصول إلى هذه الحقول باستخدام ادوات قراءة القيم getters، على سبيل المثال:

int limit = records.getTotal();

يعمل FilterRangeParam بشكل مختلف عن Filter StringParam. مفتاح النطاق هو حقل عدد غير مشفر بحيث يمكنك تنفيذ عمليات النطاق عليه.
على سبيل المثال ، يمكنك طلب جميع السجلات ذات مفتاح النطاق range-key الذي يقل عن 1000:

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

أو إذا كنت تريد فقط التحقق من المساواة:

FilterRangeParam rangeParam = new FilterRangeParam(1000);

خيارات الطلب المتاحة لـ FilterRangeParam هي:$lt, $lte, $gt, $gte.

ابحث عن سجل واحد مطابق للفلتر

إذا كنت بحاجة إلى العثور على السجل الأول المطابق للفلتر، يمكنك استخدام طريقة ابحث عن واحد findOne.
يعمل بنفس |أسلوب إبحث ولكن يعيد السجل الأول أو لا شيء إذا لم يكن هناك سجلات مطابقة.

حذف السجلات

استخدم أسلوب إحذف لحذف سجل من التخزين في InCountry. ومن الممكن القيام بذلك فقط باستخدام حقل رئيسي.

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

هنا البلد – رمز البلد الخاص بالسجل ، المفتاح – مفتاح السجل