التكاملات
التصدير إلى مستودع البيانات
صدّر بيانات NanoFlags إلى حاويتك الخاصة كل ساعة أو كل يوم: أعداد التقييمات، وسجل التدقيق، وقائمة الأعلام، والإعداد المنشور، بصيغة JSON مفصول بأسطر ومضغوط gzip، وParquet اختياريًا، مع ملف بيان لكل تصدير. في خطة Scale.
في هذه الصفحة
ما الذي يُصدَّر
يغطي كل تصدير فترة واحدة بتوقيت UTC (ساعة أو يومًا) لمؤسستك كلها. التخزين: Amazon S3 أو Cloudflare R2 أو Google Cloud Storage (بمفتاح HMAC) أو أي خدمة أخرى متوافقة مع S3.
إعداد الحاوية
- أنشئ حاوية (أو بادئة في حاوية موجودة) ومفتاح وصول يستطيع كتابة الكائنات فيها فقط. لا حاجة إلى القراءة أو الحذف.
- في NanoFlags، افتح الإعدادات ← التكاملات ← التصدير إلى مستودع البيانات بصفة مالك أو مسؤول، واختر التخزين والحاوية والبادئة الاختيارية والجدول والصيغ ومجموعات البيانات، ثم أدخل مفتاح الوصول.
- يكتب NanoFlags كائنًا اختباريًا صغيرًا (
nanoflags/v1/_connection-test.json) للتحقق من المفتاح. ويشغّل زر صدّر الفترة الأخيرة الآن تصديرًا فوريًا.
| التخزين | نقطة الوصول | المفتاح |
|---|---|---|
| Amazon S3 | من المنطقة: s3.<region>.amazonaws.com | مفتاح وصول لمستخدم IAM بالسياسة أدناه |
| Cloudflare R2 | من معرّف حسابك: <account>.r2.cloudflarestorage.com | رمز R2 API بصلاحية Object Read & Write على الحاوية (معرّف مفتاح الوصول والسر) |
| Google Cloud Storage | storage.googleapis.com | مفتاح HMAC لحساب خدمة بدور Storage Object Creator على الحاوية |
| متوافق مع S3 | عنوان https:// الخاص بك على اسم مضيف عام | مفتاح الوصول الخاص به |
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::acme-exports/nanoflags/*"
}
]
}الملفات وملف البيان
<prefix>nanoflags/v1/
evaluations/dt=2026-11-18/hour=07/part-00000.ndjson.gz
evaluations/dt=2026-11-18/hour=07/part-00000.parquet
audit_log/dt=2026-11-18/hour=07/part-00000.ndjson.gz
flags/dt=2026-11-18/hour=07/part-00000.ndjson.gz
config_snapshots/dt=2026-11-18/hour=07/part-00000.ndjson.gz
_manifests/hourly/2026-11-18T07.json (daily: _manifests/daily/2026-11-18.json, dt=… only)- التقسيم بأسلوب Hive (
dt=…/hour=…)، فتستطيع المحركات تصفية الملفات بالتاريخ. - ملفات NDJSON (
.ndjson.gz): كائن JSON واحد في كل سطر، بترميز UTF-8 ومضغوط gzip، بكل حقول كل صف. - ملفات Parquet (اختيارية): أعمدة مسطّحة؛ والقيم المتداخلة (إعدادات الأعلام وتفاصيل التدقيق والقيم المُقيَّمة) أعمدة نصية بصيغة JSON. والطوابع الزمنية بالمللي ثانية بتوقيت UTC.
- يُكتب ملف البيان أخيرًا: يكتمل التصدير حين يوجد ملف بيانه. ويسرد كل ملف مع عدد صفوفه وحجمه وبصمة SHA-256 له.
{
"format": "nanoflags-warehouse-export",
"version": 1,
"export_id": 1842,
"org_id": "5b0c…",
"granularity": "hourly",
"period_start": "2026-11-18T07:00:00.000Z",
"period_end": "2026-11-18T08:00:00.000Z",
"generated_at": "2026-11-18T09:16:02.511Z",
"formats": ["ndjson", "parquet"],
"datasets": {
"evaluations": { "available": true, "rows": 5230, "files": 4 },
"audit_log": { "available": true, "rows": 18, "files": 2 },
"experiments": { "available": false, "rows": 0, "files": 0 }
},
"files": [
{
"dataset": "evaluations",
"key": "exports/nanoflags/v1/evaluations/dt=2026-11-18/hour=07/part-00000.ndjson.gz",
"format": "ndjson",
"rows": 5000,
"bytes": 81233,
"sha256": "9f2c…"
}
]
}الجدولة وعدم التكرار وإعادة المحاولة
- تُصدَّر الفترة بعد اكتمال بياناتها: نحو ساعتين و15 دقيقة بعد انتهاء الساعة، وساعتين و30 دقيقة بعد انتهاء اليوم. تُجمَّع أعداد التقييمات كل 5 دقائق وتقبل الأحداث المتأخرة حتى ساعة.
- تُقرأ الصفوف بترتيب ثابت وتُقسَّم إلى أجزاء ثابتة الحجم، فيكتب تصدير الفترة نفسها مرة أخرى أسماء الكائنات نفسها تمامًا: إعادة التصدير تستبدل ولا تكرّر. حمّل البيانات لكل فترة (باستبدال القسم) لتبقى عملية التحميل لديك خالية من التكرار.
- تُعاد عمليات التصدير الفاشلة بفواصل متزايدة (5 ثم 10 ثم 20 ثم 40 دقيقة وهكذا، 8 محاولات). ويفشل المفتاح المرفوض أو الحاوية غير الموجودة فورًا ويجعل الوجهة متعطّلة؛ وتسرد صفحة الإعدادات آخر التصديرات بحالاتها.
- يبدأ التصدير من لحظة إعداد الوجهة (بلا استكمال لما سبق)؛ وبعد التوقف، تُستدرك حتى 48 فترة ساعية أو 7 فترات يومية فائتة.
مجموعات البيانات
| المجموعة | صف لكل | الحقول الرئيسية |
|---|---|---|
evaluations | ساعة × بيئة × علم × خدمة × SDK × سبب × قاعدة × قيمة | project_key, environment_key, hour, flag_key, service, sdk, reason, rule_index, value, sampled_events, rated_events, weighted_events, sample_rate_min, sample_rate_max |
audit_log | إدخال تدقيق أُنشئ في الفترة | id, created_at, project_key, environment_key, actor_id, actor_name, action, object_type, object_id, object_label, summary, detail |
flags | علم (القائمة وقت التصدير) | project_key, flag_id, key, name, description, type, purpose, permanent, client_exposed, review_date, archived_at, created_at, owner_name |
config_snapshots | بيئة: المراجعة المنشورة في نهاية الفترة | project_key, environment_key, revision, checksum, published_at, kind, flags, segments |
experiments | تعرّض أو مقياس (بعد تفعيل التجارب) | تُدرج في ملف البيان كغير متاحة حتى ذلك الحين |
يعدّ sampled_events أحداث التقييم التي أرسلتها حزم SDK (بالعيّنات)؛ ويجمع weighted_events مقلوب معدل العيّنة للأحداث المعروف معدلها، وهو تقدير لعدد التقييمات كلها.
التحميل في BigQuery
يقرأ BigQuery ملفات NDJSON المضغوطة وParquet من Cloud Storage. ومع S3 أو R2، انسخ الملفات بخدمة Storage Transfer Service، أو صدّر مباشرة إلى حاوية Cloud Storage.
-- One period at a time; OVERWRITE PARTITIONS keeps a repeated load idempotent.
CREATE TABLE IF NOT EXISTS nanoflags.evaluations (
org_id STRING, project_key STRING, environment_key STRING, hour TIMESTAMP, flag_key STRING,
service STRING, sdk STRING, reason STRING, rule_index INT64, value JSON,
sampled_events INT64, rated_events INT64, weighted_events FLOAT64,
sample_rate_min FLOAT64, sample_rate_max FLOAT64, last_at TIMESTAMP
) PARTITION BY DATE(hour);
LOAD DATA OVERWRITE nanoflags.evaluations
PARTITIONS (DATE(hour) = '2026-11-18')
FROM FILES (
format = 'JSON',
uris = ['gs://acme-exports/nanoflags/v1/evaluations/dt=2026-11-18/*.ndjson.gz']
);
-- Or with the bq tool, Parquet files and Hive partitions:
-- bq load --source_format=PARQUET --hive_partitioning_mode=AUTO \
-- --hive_partitioning_source_uri_prefix=gs://acme-exports/nanoflags/v1/audit_log/ \
-- nanoflags.audit_log 'gs://acme-exports/nanoflags/v1/audit_log/dt=2026-11-18/*.parquet'نصيحة
جدول خارجي فوق nanoflags/v1/evaluations/* بتقسيم Hive يستعلم الملفات في مكانها دون تحميل.
التحميل في Snowflake
CREATE STAGE nanoflags_stage
URL = 's3://acme-exports/nanoflags/v1/'
STORAGE_INTEGRATION = acme_s3; -- or CREDENTIALS = (...); R2 and GCS work through their S3 endpoints
CREATE FILE FORMAT nanoflags_ndjson TYPE = JSON COMPRESSION = GZIP;
CREATE TABLE IF NOT EXISTS nanoflags_evaluations_raw (v VARIANT, file STRING);
-- COPY remembers the files it loaded (64 days): running it again only loads new or changed files.
COPY INTO nanoflags_evaluations_raw (v, file)
FROM (SELECT $1, METADATA$FILENAME FROM @nanoflags_stage/evaluations/)
FILE_FORMAT = (FORMAT_NAME = nanoflags_ndjson)
PATTERN = '.*[.]ndjson[.]gz';
CREATE OR REPLACE VIEW nanoflags_evaluations AS
SELECT v:project_key::string AS project_key, v:environment_key::string AS environment_key,
v:hour::timestamp_tz AS hour, v:flag_key::string AS flag_key, v:service::string AS service,
v:reason::string AS reason, v:value AS value, v:sampled_events::number AS sampled_events,
v:weighted_events::float AS weighted_events
FROM nanoflags_evaluations_raw
QUALIFY ROW_NUMBER() OVER (PARTITION BY file, v:flag_key, v:hour, v:environment_key, v:service, v:sdk, v:reason, v:rule_index, v:value ORDER BY 1) = 1;
-- Parquet instead: CREATE FILE FORMAT nanoflags_parquet TYPE = PARQUET;
-- COPY INTO nanoflags_audit_log FROM @nanoflags_stage/audit_log/ FILE_FORMAT = (FORMAT_NAME = nanoflags_parquet)
-- MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE PATTERN = '.*[.]parquet';التحميل في Redshift
CREATE TABLE IF NOT EXISTS nanoflags_audit_log (
id BIGINT, org_id VARCHAR(36), created_at TIMESTAMPTZ, project_key VARCHAR(64), environment_key VARCHAR(64),
actor_id VARCHAR(36), actor_name VARCHAR(256), action VARCHAR(128), object_type VARCHAR(64),
object_id VARCHAR(128), object_label VARCHAR(512), summary VARCHAR(2048), detail SUPER
);
-- Replace one period in a transaction, so loading it again is idempotent.
BEGIN;
DELETE FROM nanoflags_audit_log WHERE created_at >= '2026-11-18' AND created_at < '2026-11-19';
COPY nanoflags_audit_log
FROM 's3://acme-exports/nanoflags/v1/audit_log/dt=2026-11-18/'
IAM_ROLE 'arn:aws:iam::123456789012:role/redshift-nanoflags'
FORMAT AS JSON 'auto' GZIP TIMEFORMAT 'auto';
COMMIT;
-- A prefix COPY reads every object under it. When Parquet is also written, list the .ndjson.gz keys of the
-- NanoFlags manifest in a COPY manifest file ({"entries": [{"url": "s3://…", "mandatory": true}]}) and add MANIFEST,
-- or load the Parquet files instead with FORMAT AS PARQUET and the same manifest approach.الأمان
- تشفّر خدمة الإشعارات في NanoFlags مفتاح الوصول (AES-256-GCM) بمفتاح لا تملكه قاعدة البيانات، ولا يظهر مجددًا ولا يُرسَل إلى أي متصفح.
- يُعِدّ التصدير المالكون والمسؤولون فقط؛ وكل تغيير واختبار وتصدير فاشل مسجّل في سجل التدقيق.
- يجب أن تكون نقاط الوصول https:// على اسم مضيف عام؛ ولا تُتبَع عمليات إعادة التوجيه.
- تحتوي التصديرات بيانات مؤسستك فقط. يتضمن سجل التدقيق أسماء الأعضاء؛ وتتضمن أعداد التقييمات القيم المُقيَّمة دون سياقات التقييم.
الخطة
التصدير إلى مستودع البيانات متاح في خطة Scale. راجع الخطط والحدود.