انتقل إلى المحتوى
NanoFlags
ابدأ مجانًا

التكاملات

التصدير إلى مستودع البيانات

صدّر بيانات NanoFlags إلى حاويتك الخاصة كل ساعة أو كل يوم: أعداد التقييمات، وسجل التدقيق، وقائمة الأعلام، والإعداد المنشور، بصيغة JSON مفصول بأسطر ومضغوط gzip، وParquet اختياريًا، مع ملف بيان لكل تصدير. في خطة Scale.

ما الذي يُصدَّر

يغطي كل تصدير فترة واحدة بتوقيت UTC (ساعة أو يومًا) لمؤسستك كلها. التخزين: Amazon S3 أو Cloudflare R2 أو Google Cloud Storage (بمفتاح HMAC) أو أي خدمة أخرى متوافقة مع S3.

إعداد الحاوية

  1. أنشئ حاوية (أو بادئة في حاوية موجودة) ومفتاح وصول يستطيع كتابة الكائنات فيها فقط. لا حاجة إلى القراءة أو الحذف.
  2. في NanoFlags، افتح الإعدادات ← التكاملات ← التصدير إلى مستودع البيانات بصفة مالك أو مسؤول، واختر التخزين والحاوية والبادئة الاختيارية والجدول والصيغ ومجموعات البيانات، ثم أدخل مفتاح الوصول.
  3. يكتب 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 Storagestorage.googleapis.comمفتاح HMAC لحساب خدمة بدور Storage Object Creator على الحاوية
متوافق مع S3عنوان https:// الخاص بك على اسم مضيف عاممفتاح الوصول الخاص به
أدنى سياسة S3
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::acme-exports/nanoflags/*"
    }
  ]
}

الملفات وملف البيان

text
<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.

BigQuery
-- 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

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

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. راجع الخطط والحدود.