مرجع API

مرجع API لـ ClickStack لإدارة لوحات المعلومات والتنبيهات والمصادر برمجيًا

يوفّر ClickStack واجهة برمجة تطبيقات REST لإدارة لوحات المعلومات والتنبيهات ومصادر البيانات برمجيًا. وهذه الواجهة متاحة لكلٍّ من عمليات نشر Managed ClickStack ‏(ClickHouse Cloud) وClickStack Open Source، مع اختلاف نقاط النهاية وآلية المصادقة بينهما.

​

وثائق مرجع API

Managed ClickStack

بالنسبة إلى Managed ClickStack، يتم الوصول إلى API عبر ClickHouse Cloud API. تتوفر نقاط نهاية ClickStack في مواصفات Cloud API.

نقاط النهاية التالية متاحة:

المورد	العمليات
لوحات المعلومات	إنشاء لوحات المعلومات وعرضها وجلبها وتحديثها وحذفها
التنبيهات	إنشاء التنبيهات وعرضها وجلبها وتحديثها وحذفها
المصادر	عرض مصادر البيانات

Open Source ClickStack

بالنسبة إلى ClickStack Open Source، تُحفَظ مواصفات API الكاملة في مستودع HyperDX، ويمكن استعراضها تفاعليًا أو تنزيلها كمواصفات OpenAPI:

• مرجع API التفاعلي
• تنزيل مواصفات OpenAPI ‏(JSON)

نقاط النهاية التالية متاحة:

المورد	العمليات
لوحات المعلومات	إنشاء لوحات المعلومات وعرضها وجلبها وتحديثها وحذفها
التنبيهات	إنشاء التنبيهات وعرضها وجلبها وتحديثها وحذفها
المخططات	الاستعلام عن بيانات السلاسل الزمنية (POST فقط)
المصادر	عرض مصادر البيانات
Webhooks	عرض Webhooks

​

المصادقة

Managed ClickStack

يستخدم Managed ClickStack مفتاح ClickHouse Cloud API للمصادقة عبر مصادقة HTTP الأساسية. لإنشاء مفاتيح API وإدارتها، راجع إدارة مفاتيح API.

ضمّن معرّف المفتاح والقيمة السرية باستخدام مصادقة HTTP الأساسية:

export KEY_ID=<your_key_id>
export KEY_SECRET=<your_key_secret>

curl --user $KEY_ID:$KEY_SECRET \
  https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/dashboards

Open Source ClickStack

يستخدم ClickStack Open Source Bearer token للمصادقة عبر مفتاح وصول API شخصي.

للحصول على مفتاح API:

1. افتح HyperDX على عنوان URL الخاص بـ ClickStack لديك (على سبيل المثال: http://localhost:8080)
2. أنشئ حسابًا أو سجّل الدخول عند الحاجة
3. انتقل إلى Team Settings → API Keys
4. انسخ مفتاح وصول API الشخصي الخاص بك

يختلف هذا عن مفتاح API للاستيعاب الموجود في Team Settings، والذي يُستخدم لمصادقة بيانات القياس عن بُعد المُرسلة إلى مجمّع OpenTelemetry.

يعمل خادم API على المنفذ 8000 افتراضيًا (بشكل منفصل عن واجهة المستخدم على المنفذ 8080). عند استخدام صورة Docker المتكاملة، تأكد من ربط هذا المنفذ صراحةً:

docker run -p 8080:8080 -p 8000:8000 -p 4317:4317 -p 4318:4318 docker.hyperdx.io/hyperdx/hyperdx-all-in-one

ضمّن المفتاح في ترويسة Authorization:

curl -H "Authorization: Bearer <YOUR_API_KEY>" \
  http://localhost:8000/api/v2/dashboards

​

عنوان URL الأساسي وتنسيق الطلب

Managed ClickStack

تُرسَل جميع طلبات API الخاصة بـ Managed ClickStack إلى ClickHouse Cloud API:

https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/<resource>

يمكنك العثور على Organization ID الخاص بك في ClickHouse Cloud console ضمن Organization → Organization details. ويظهر Service ID الخاص بك في عنوان URL الخاص بالخدمة أو في صفحة تفاصيل الخدمة.

​

مثال: سرد لوحات المعلومات

curl --user $KEY_ID:$KEY_SECRET \
  https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/dashboards

​

مثال: إنشاء تنبيه

curl -X POST --user $KEY_ID:$KEY_SECRET \
  -H "Content-Type: application/json" \
  -d '{
    "dashboardId": "<DASHBOARD_ID>",
    "tileId": "<TILE_ID>",
    "threshold": 100,
    "interval": "1h",
    "source": "tile",
    "thresholdType": "above",
    "channel": {
      "type": "webhook",
      "webhookId": "<WEBHOOK_ID>"
    },
    "name": "Error Spike Alert",
    "message": "Error rate exceeded 100 in the last hour"
  }' \
  https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickstack/alerts

Open Source ClickStack

تُرسَل جميع طلبات API الخاصة بـ Open Source ClickStack إلى خادم HyperDX API على المنفذ 8000:

http://<YOUR_HYPERDX_HOST>:8000/api/v2/<resource>

على سبيل المثال، في عملية نشر محلية افتراضية:

http://localhost:8000/api/v2/dashboards

​

مثال: سرد لوحات المعلومات

curl -H "Authorization: Bearer <YOUR_API_KEY>" \
  http://localhost:8000/api/v2/dashboards

​

مثال: إنشاء تنبيه

curl -X POST \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "dashboardId": "<DASHBOARD_ID>",
    "tileId": "<TILE_ID>",
    "threshold": 100,
    "interval": "1h",
    "source": "tile",
    "thresholdType": "above",
    "channel": {
      "type": "webhook",
      "webhookId": "<WEBHOOK_ID>"
    },
    "name": "Error Spike Alert",
    "message": "Error rate exceeded 100 in the last hour"
  }' \
  http://localhost:8000/api/v2/alerts

​

مثال: الاستعلام عن بيانات سلاسل المخطط

curl -X POST \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": 1647014400000,
    "endTime": 1647100800000,
    "granularity": "1h",
    "series": [
      {
        "sourceId": "<SOURCE_ID>",
        "aggFn": "count",
        "where": "SeverityText:error",
        "groupBy": []
      }
    ]
  }' \
  http://localhost:8000/api/v2/charts/series