Set up docs MCPيوفّر ClickStack واجهة برمجة تطبيقات REST لإدارة لوحات المعلومات والتنبيهات ومصادر البيانات برمجيًا. وهذه الواجهة متاحة لكلٍّ من عمليات نشر Managed ClickStack (ClickHouse Cloud) وClickStack Open Source، مع اختلاف نقاط النهاية وآلية المصادقة بينهما.
وثائق مرجع واجهة برمجة تطبيقات
بالنسبة إلى Managed ClickStack، يتم الوصول إلى واجهة برمجة تطبيقات عبر واجهة برمجة تطبيقات ClickHouse Cloud. تتوفر نقاط نهاية ClickStack في مرجع Cloud واجهة برمجة تطبيقات.
نقاط النهاية التالية متاحة:
| المورد | العمليات |
|---|---|
| لوحات المعلومات | إنشاء لوحات المعلومات وعرضها وجلبها وتحديثها وحذفها |
| التنبيهات | إنشاء التنبيهات وعرضها وجلبها وتحديثها وحذفها |
| المصادر | عرض مصادر البيانات |
بالنسبة إلى ClickStack Open Source، تُحفَظ مواصفات واجهة برمجة تطبيقات الكاملة في مستودع HyperDX ويمكن استعراضها تفاعليًا أو تنزيلها كمواصفات OpenAPI:
نقاط النهاية التالية متاحة:
| المورد | العمليات |
|---|---|
| لوحات المعلومات | إنشاء لوحات المعلومات وعرضها وجلبها وتحديثها وحذفها |
| التنبيهات | إنشاء التنبيهات وعرضها وجلبها وتحديثها وحذفها |
| المخططات | الاستعلام عن بيانات السلاسل الزمنية (POST فقط) |
| المصادر | عرض مصادر البيانات |
| Webhooks | عرض Webhooks |
المصادقة
يستخدم Managed ClickStack مفتاح واجهة برمجة تطبيقات ClickHouse Cloud للمصادقة عبر مصادقة HTTP الأساسية. لإنشاء مفاتيح واجهة برمجة تطبيقات وإدارتها، راجع إدارة مفاتيح واجهة برمجة تطبيقات.
ضمّن معرّف المفتاح والقيمة السرية باستخدام مصادقة 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يستخدم ClickStack Open Source Bearer token للمصادقة عبر مفتاح وصول واجهة برمجة تطبيقات شخصي.
للحصول على مفتاح واجهة برمجة تطبيقات:
- افتح HyperDX على عنوان URL الخاص بـ ClickStack لديك (على سبيل المثال: http://localhost:8080)
- أنشئ حسابًا أو سجّل الدخول عند الحاجة
- انتقل إلى Team Settings → API Keys
- انسخ مفتاح وصول واجهة برمجة تطبيقات الشخصي الخاص بك
يعمل خادم واجهة برمجة تطبيقات على المنفذ 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 الأساسي وتنسيق الطلب
تُرسَل جميع طلبات 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تُرسَل جميع طلبات 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