OpenAPI لـ ClickHouse Managed Postgres

أدِر خدمات ClickHouse Managed Postgres لديك باستخدام OpenAPI الخاص بنا

استخدم ClickHouse OpenAPI للتحكم برمجيًا في خدمات ClickHouse Managed Postgres لديك، تمامًا كما تفعل مع خدمات ClickHouse. كما تتيح واجهة برمجة التطبيقات نفسها أيضًا [نقطة نهاية Prometheus] لاستخراج مقاييس الخدمة. هل أنت على دراية مسبقة بـOpenAPI؟ احصل على [مفاتيح API] وانتقل مباشرةً إلى مرجع API لـ ClickHouse Managed Postgres. وإن لم تكن كذلك، فتابع معنا للاطلاع على شرح سريع.

​

مفاتيح API

يتطلب استخدام ClickHouse OpenAPI المصادقة؛ راجع [مفاتيح API] لمعرفة كيفية إنشائها. ثم استخدمها كبيانات اعتماد Basic Auth على النحو التالي:

KEY_ID=mykeyid
KEY_SECRET=mykeysecret

curl -s --user "$KEY_ID:$KEY_SECRET" https://api.clickhouse.cloud/v1/organizations | jq

​

معرّف المؤسسة

بعد ذلك، ستحتاج إلى معرّف مؤسستك.

1. حدِّد اسم مؤسستك في الزاوية السفلية اليسرى من الواجهة.
2. حدِّد تفاصيل المؤسسة.
3. اضغط على أيقونة النسخ إلى يمين معرّف المؤسسة لنسخه مباشرةً إلى الحافظة.

يمكنك الآن استخدامه في طلباتك، كما يلي:

ORG_ID=myorgid

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres" | jq

لقد أجريت الآن أول طلب إلى واجهة برمجة تطبيقات Postgres: تعرض list API أعلاه جميع خوادم Postgres في مؤسستك. يُفترض أن يكون الناتج على النحو التالي:

{
  "result": [
    {
      "id": "ee2fef9f-b443-8ad0-8c9b-724390cdb826",
      "name": "oltp",
      "provider": "aws",
      "region": "eu-west-2",
      "postgresVersion": "18",
      "size": "r6gd.medium",
      "storageSize": 59,
      "haType": "none",
      "tags": [],
      "isPrimary": true,
      "state": "running",
      "createdAt": "2026-05-25T16:42:16+00:00"
    }
  ],
  "requestId": "c128d830-5769-4c82-8235-f79aa69d1ebf",
  "status": 200
}

​

CRUD

لنلقِ نظرة على دورة حياة خدمة Postgres.

​

إنشاء

أولًا، أنشئ خدمة جديدة باستخدام [واجهة برمجة تطبيقات create]. وتتطلب الخصائص التالية في نص JSON للطلب:

• name: اسم خدمة Postgres الجديدة
• provider: اسم موفّر السحابة: aws (أو gcp في المعاينة الخاصة)
• region: المنطقة ضمن شبكة الموفّر التي ستُنشر فيها الخدمة
• size: حجم الآلة الافتراضية

راجع وثائق [واجهة برمجة تطبيقات create] للاطّلاع على القيم الممكنة لهذه الخصائص. بالإضافة إلى ذلك، لنحدّد Postgres 18 بدلًا من الإصدار الافتراضي، 17:

create_data='{
  "name": "my postgres",
  "provider": "aws",
  "region": "us-west-2",
  "postgresVersion": "18",
  "size": "r8gd.large"
}'

استخدم الآن هذه البيانات لإنشاء مثيل جديد؛ لاحظ أن ذلك يتطلب ترويسة Content-Type. احفظ الاستجابة: فهي الوحيدة التي تتضمن بيانات اعتماد الخدمة (كما تُرجعها استجابة [إعادة تعيين كلمة المرور] أيضًا عندما لا يوفّر الطلب كلمة مرور):

pg_created=$(curl -s --user "$KEY_ID:$KEY_SECRET" -H 'Content-Type: application/json' \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres" \
    -d "$create_data")
echo "$pg_created" | jq

عند نجاح العملية، سيُنشئ مثيلًا جديدًا ويُرجع معلومات عنه، بما في ذلك بيانات الاتصال:

{
  "result": {
    "id": "67b4bc12-8582-45d0-8806-fe9b2e5a54e6",
    "name": "my postgres",
    "provider": "aws",
    "region": "us-west-2",
    "postgresVersion": "18",
    "size": "r8gd.large",
    "storageSize": 118,
    "haType": "none",
    "tags": [],
    "connectionString": "postgres://postgres:[e-mail]:5432/postgres?channel_binding=require",
    "username": "postgres",
    "password": "vV6cfEr2p_-TzkCDrZOx",
    "hostname": "my-postgres-6d8d2e3e.pg7myrd1j06p3gx4zrm2ze8qz6.c0.us-west-2.aws.pg.clickhouse-dev.com",
    "isPrimary": true,
    "state": "creating"
  },
  "requestId": "a5957990-dbe5-46fd-b5ce-a7f8f79e50fe",
  "status": 200
}

​

قراءة

استخدم القيمة id من الاستجابة لاسترجاع الخدمة مرة أخرى:

PG_ID=67b4bc12-8582-45d0-8806-fe9b2e5a54e6
curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq

ستكون المخرجات مشابهةً لـ JSON المُعاد عند الإنشاء، من دون بيانات الاعتماد، لكن راقب state؛ فعندما تتغير إلى running، يكون الخادم جاهزًا:

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq .result.state

"running"

يمكنك الآن استخدام الخاصية connectionString المحفوظة من استجابة الإنشاء للاتصال، على سبيل المثال عبر psql:

$ psql "$(echo "$pg_created" | jq -r .result.connectionString)"

psql (18.3)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: postgresql)
Type "help" for help.

postgres=#

اكتب \q للخروج من psql.

​

تحديث

تدعم [واجهة برمجة تطبيقات patch] تحديث مجموعة فرعية من خصائص خدمة Managed Postgres باستخدام RFC 7396 JSON Merge Patch. وقد تكتسب الوسوم أهمية خاصة في عمليات النشر المعقدة؛ ما عليك سوى إرسالها وحدها ضمن الطلب:

curl -sX PATCH --user "$KEY_ID:$KEY_SECRET" -H 'Content-Type: application/json' \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    -d '{"tags": [{"key": "Environment", "value": "production"}]}' \
    | jq .result

يجب أن تتضمن البيانات المُسترجعة الوسوم الجديدة:

{
  "id": "67b4bc12-8582-45d0-8806-fe9b2e5a54e6",
  "name": "my postgres",
  "provider": "aws",
  "region": "us-west-2",
  "postgresVersion": "18",
  "size": "r8gd.large",
  "storageSize": 118,
  "haType": "none",
  "tags": [
    {
      "key": "Environment",
      "value": "production"
    }
  ],
  "username": "postgres",
  "hostname": "my-postgres-6d8d2e3e.$PG_ID.c0.us-west-2.aws.pg.clickhouse-dev.com",
  "isPrimary": true,
  "state": "running"
}

يوفّر OpenAPI نقاط نهاية إضافية لتحديث الخصائص غير المدعومة من خلال [واجهة برمجة تطبيقات patch]. على سبيل المثال، لتحديث [تهيئة Postgres]، استخدم [واجهة برمجة تطبيقات config]:

curl -s --user "$KEY_ID:$KEY_SECRET" -H 'Content-Type: application/json' \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID/config" \
    -d '{"pgConfig": {"max_connections": "42"}, "pgBouncerConfig": {}}' | jq

سيُظهر الناتج التهيئة المحدَّثة، بالإضافة إلى رسالة توضّح تبعات هذا التغيير:

{
  "result":{
    "pgConfig": {
      "max_connections": "42"
    },
    "pgBouncerConfig": {},
    "message": "The changes in the following parameters require a database restart to take effect: max_connections. You can restart the database by using the restart endpoint."
  },
  "requestId":"fdec06f2-66f7-45b4-9f82-0c051aba20aa",
  "status": 200
}

​

حذف

استخدم [واجهة برمجة تطبيقات الحذف] لحذف خدمة Postgres.

يؤدي حذف خدمة Postgres إلى إزالة الخدمة بالكامل وجميع بياناتها. تأكد من توفّر نسخة احتياطية لديك أو من أنك قمت بترقية نسخة متماثلة إلى النسخة الأساسية قبل حذف الخدمة.

curl -sX DELETE --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID" \
    | jq

عند النجاح، ستُرجِع الاستجابة رمز الحالة 200، على سبيل المثال:

{
  "requestId": "ac9bbffa-e370-410c-8bdd-bd24bf3d7f82",
  "status": 200
}

​

المراقبة

توفّر نقطتا نهاية متوافقتان مع Prometheus مقاييس CPU والذاكرة والإدخال/الإخراج والاتصالات والمعاملات لخدمات ClickHouse Managed Postgres: تُرجع إحداهما المقاييس لكل خدمة في المؤسسة، بينما تُرجع الأخرى المقاييس لخدمة واحدة. راجع صفحة [نقطة نهاية Prometheus] لمعرفة كيفية الإعداد، و[مرجع المقاييس] للاطلاع على القائمة الكاملة للمقاييس.

​

Query insights

إن بيانات القياس عن بُعد الخاصة بكل عبارة، والتي تستند إليها علامة التبويب Query Insights في الكونسول السحابي، متاحة أيضًا برمجيًا. توفّر نقطتا نهاية أبطأ أنماط الاستعلامات في خدمة: تسرد إحداهما جميع الأنماط مرتبةً حسب التأثير، بينما تُرجع الأخرى نمطًا واحدًا مع أحدث عمليات تنفيذه.

​

إدراج أنماط الاستعلامات البطيئة

تعيد [واجهة برمجة تطبيقات الأنماط البطيئة] مقاييس مجمّعة لأبطأ أنماط الاستعلامات التي تم رصدها خلال نافذة زمنية. هذه النافذة مطلوبة — مرّر from_date وto_date كطوابع زمنية بتنسيق RFC 3339:

FROM=2026-05-25T00:00:00Z
TO=2026-05-26T00:00:00Z

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID/slowQueryPatterns?from_date=$FROM&to_date=$TO" \
    | jq

تُعرَض النتائج افتراضيًا بحيث تظهر الأنماط الأكثر كلفة أولًا، مرتبة حسب total_duration ترتيبًا تنازليًا. فرّز حسب عدّاد مختلف باستخدام sort_by (على سبيل المثال p99_duration أو call_count أو total_wal_bytes) واعكس الاتجاه باستخدام sort_order. ضيّق مجموعة النتائج باستخدام عوامل التصفية db_name وdb_user وdb_operation وapp، وتصفّح صفحاتها باستخدام limit و offset.

يمثّل كلّ ناتج نمطًا مُطبَّعًا واحدًا، مع إزالة القيم الحرفية منه والإبلاغ عن المدد بوحدة الميكروثانية:

{
  "result": [
    {
      "queryId": "-4748036479882663975",
      "queryText": "SELECT * FROM orders WHERE customer_id = $1 ORDER BY created_at DESC LIMIT $2",
      "dbName": "sales",
      "dbUser": "orders_service",
      "dbOperation": "SELECT",
      "app": "orders-api",
      "callCount": 84213,
      "errorCount": 0,
      "totalDurationUs": 1012384556,
      "avgDurationUs": 12021,
      "maxDurationUs": 482915,
      "p50DurationUs": 9874,
      "p95DurationUs": 28431,
      "p99DurationUs": 41200,
      "totalRows": 842130,
      "totalSharedBlksRead": 19284,
      "totalSharedBlksHit": 48217734,
      "totalCpuTimeUs": 938472113,
      "totalWalBytes": 0
    }
  ],
  "requestId": "c128d830-5769-4c82-8235-f79aa69d1ebf",
  "status": 200
}

إن queryId هو قيمة hash موقَّعة بطول 64 بت للعبارة المُطبَّعة، لذلك يكون سالبًا في كثير من الأحيان. أعد تمريره كما هو تمامًا — بما في ذلك الشرطة - في البداية — لاسترجاع نمط استعلام واحد.

​

الحصول على نمط استعلام بطيء

مرّر queryId من استجابة القائمة إلى [واجهة برمجة تطبيقات نمط الاستعلامات البطيئة] للحصول على المقاييس المجمّعة لهذا النمط إلى جانب أحدث عمليات التنفيذ الفردية له. القيم db_name وdb_user وdb_operation التي تُعرّف هذا النمط مطلوبة:

QUERY_ID=-4748036479882663975

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID/slowQueryPatterns/$QUERY_ID?db_name=sales&db_user=orders_service&db_operation=SELECT" \
    | jq

تتضمن الاستجابة نفس ناتج التجميع الموجود في نقطة نهاية القائمة ضمن aggregate، بالإضافة إلى مصفوفة recentExecutions. ويتضمن كل تنفيذ العدادات الكاملة الخاصة به — إدخال/إخراج الكتل المشتركة والمؤقتة، ووقت CPU للمستخدم والنظام، والعمّال المتوازيون، وJIT، وWAL — وهي العدادات نفسها التي تفصّلها [اللوحة الجانبية للتفاصيل] في الكونسول:

{
  "result": {
    "aggregate": {
      "queryId": "-4748036479882663975",
      "queryText": "SELECT * FROM orders WHERE customer_id = $1 ORDER BY created_at DESC LIMIT $2",
      "dbName": "sales",
      "dbUser": "orders_service",
      "dbOperation": "SELECT",
      "callCount": 84213,
      "avgDurationUs": 12021,
      "p99DurationUs": 41200
    },
    "recentExecutions": [
      {
        "timestamp": "2026-05-25T16:42:09Z",
        "durationUs": 41200,
        "rows": 10,
        "sharedBlksHit": 412,
        "sharedBlksRead": 3,
        "tempBlksWritten": 0,
        "cpuUserTimeUs": 38211,
        "cpuSysTimeUs": 1044,
        "parallelWorkersPlanned": 0,
        "parallelWorkersLaunched": 0,
        "walBytes": 0,
        "serverRole": "primary"
      }
    ]
  },
  "requestId": "a5957990-dbe5-46fd-b5ce-a7f8f79e50fe",
  "status": 200
}

يختصر المثال كلا الكائنين مراعاةً للإيجاز؛ وتُرجع واجهة برمجة تطبيقات مجموعة العدادات الكاملة الموثقة ضمن per-execution counters.

​

سجلات الخادم

تتوفر سجلات خادم PostgreSQL المعروضة في عارض السجلات ضمن الكونسول السحابي أيضًا برمجيًا. تُرجع [واجهة برمجة تطبيقات السجلات] إدخالات سجل فردية لخدمة خلال نافذة زمنية. وكما هو الحال مع Query Insights، يلزم تحديد النافذة، لذا مرّر from_date وto_date كطوابع زمنية بتنسيق RFC 3339. يجب ألا يتجاوز النطاق 30 يومًا، ويجب أن يكون to_date بعد from_date:

FROM=2026-05-25T00:00:00Z
TO=2026-05-26T00:00:00Z

curl -s --user "$KEY_ID:$KEY_SECRET" \
    "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/postgres/$PG_ID/logs?from_date=$FROM&to_date=$TO" \
    | jq

تُعاد الإدخالات بحيث يكون الأحدث أولًا؛ اعكس الترتيب باستخدام sort_order (asc أو desc). رشّح حسب مستوى خطورة واحد باستخدام severity (مثل ERROR أو WARNING أو LOG)، وطابِق سلسلة فرعية حساسة لحالة الأحرف في متن السجل باستخدام body_contains، وتصفّح النتائج باستخدام limit وoffset.

يتضمن كل إدخال timestamp وseverity وbody الخام. ويكون المتن دائمًا سلسلة نصية: تُعاد أسطر السجل المهيكلة بتنسيق JSON، بينما تُعاد الأسطر العادية كما هي:

{
  "result": [
    {
      "timestamp": "2026-05-25T16:42:09.512844Z",
      "severity": "ERROR",
      "body": "{\"message\":\"deadlock detected\",\"detail\":\"Process 42 waits for ShareLock\"}"
    },
    {
      "timestamp": "2026-05-25T16:41:58.004120Z",
      "severity": "LOG",
      "body": "connection received: host=10.0.0.7 port=54210 user=orders_service database=sales"
    }
  ],
  "limit": 50,
  "offset": 0,
  "requestId": "b0d5c3a1-9f2e-4a7c-8b1d-3e6f0a2c4d55",
  "status": 200
}

تقسّم نقطة النهاية النتائج إلى صفحات باستخدام limit وoffset بدلاً من إرجاع عدد إجمالي؛ زِد offset حتى تُرجع الصفحة عددًا من الإدخالات أقل من limit.