حوكمة واجهة برمجة تطبيقات الإنتاج على AceDataCloud

مفتاح واجهة برمجة تطبيقات الإنتاج ليس مجرد سلسلة سرية. إنه نقطة تحكم لـ من يمكنه استدعاء ماذا، وكم يمكنه استهلاك، ومدة استمرار الوصول، وأي تطبيق يدفع، وكيف يمكن تتبع الحادث.

يعرض AceDataCloud هذه الضوابط عبر أربع طبقات مترابطة:

  1. إصدار بيانات الاعتماد — إنشاء مفتاح لتطبيق محدد.
  2. سياسة رصيد التطبيق — تحديد مصدر خصم الاستخدام وما يحدث عند انخفاض الحصة.
  3. قابلية ملاحظة الاستخدام — تتبع الحالة والتكلفة والكمون وواجهة برمجة التطبيقات والتطبيق وبيانات الاعتماد.
  4. دورة حياة بيانات الاعتماد — تحديث القيود وتدوير الأسرار وإلغاء الوصول.

حلقة التحكم في حوكمة واجهة برمجة تطبيقات الإنتاج

يحوّل هذا الدليل واجهات برمجة تطبيقات الإدارة الفردية للمنصة إلى نموذج تشغيل عملي واحد.

أولاً، افصل بين نوعَي بيانات الاعتماد

يستخدم AceDataCloud بيانات اعتماد مختلفة لواجهات مختلفة:

بيانات الاعتماد تُستخدم لـ المضيف المعتاد
رمز الحساب / رمز المنصة إدارة الحساب: التطبيقات وبيانات الاعتماد والأرصدة والاستخدام والطلبات platform.acedata.cloud/api/v1/**
بيانات اعتماد واجهة برمجة التطبيقات استدعاء واجهات برمجة تطبيقات الأعمال لخدمة ما api.acedata.cloud/**

لا يمكن استبدال أحدهما بالآخر. لا ينبغي استخدام بيانات اعتماد واجهة برمجة تطبيقات الأعمال لاستدعاء نقاط نهاية الإدارة، ولا ينبغي تضمين رمز المنصة في تطبيق كمفتاح واجهة برمجة تطبيقات الأعمال الخاص به.

ينشئ هذا الفصل حدًا أمنيًا مفيدًا:

  • احتفظ برموز المنصة في بيئة عمليات محكومة بإحكام.
  • امنح كل عبء عمل بيانات اعتماد واجهة برمجة تطبيقات خاصة به.
  • دع خدمات وقت التشغيل تستدعي فقط واجهات برمجة تطبيقات الأعمال التي تحتاجها.
  • دع CI أو خدمة إدارية تنفذ إدارة بيانات الاعتماد والأرصدة.

أصدر بيانات اعتماد واحدة لكل عبء عمل وبيئة

أنشئ بيانات اعتماد باستخدام POST https://platform.acedata.cloud/api/v1/credentials/ باستعمال رمز الحساب.

يمكن أن يتضمن طلب موجه للإنتاج بالحد الأدنى اسم عرض وحدًا مستقلًا للاستهلاك وانتهاء صلاحية وقائمة سماح لواجهات برمجة التطبيقات:

curl -X POST 'https://platform.acedata.cloud/api/v1/credentials/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"application_id\": \"${APPLICATION_ID}\",
    \"name\": \"prod-support-agent\",
    \"limited_amount\": 100,
    \"expired_at\": \"2027-01-01T00:00:00Z\",
    \"allowed_api_ids\": [\"${CHAT_API_ID}\"],
    \"metadata\": {\"environment\": \"production\", \"owner\": \"support-platform\"}
  }"

يدعم عقد الإنشاء ما يلي:

الحقل غرض الحوكمة
application_id يربط الاستخدام بالتطبيق المستهدف
name يجعل عبء العمل قابلاً للتعرّف عليه في عمليات التدقيق
limited_amount يحدد حد استخدام مستقل لبيانات الاعتماد؛ تعني null عدم وجود حد مستقل
expired_at يحدد وصولًا تلقائيًا محدد المدة
allowed_api_ids يقيد بيانات الاعتماد بواجهات برمجة تطبيقات مختارة
host يخزن معلومات مضيف بيانات الاعتماد عند الاقتضاء
for_user_id يتيح لمالك التطبيق إصدار بيانات اعتماد مفوضة لمستخدم آخر
tags / metadata يسجل سياق البيئة أو الفريق أو النظام أو تذكرة التغيير

تتم تسوية مصفوفة allowed_api_ids الفارغة إلى عدم وجود تقييد. لا ترسل مصفوفة فارغة عندما تكون نيتك هي “عدم السماح بأي شيء”. استخدم قائمة سماح فعلية لواجهات برمجة التطبيقات.

تعيد خدمات API/Agent عادةً بيانات اعتماد من نوع Token. تعيد خدمات Proxy عادةً هوية اسم مستخدم/كلمة مرور، ويسمح تطبيق Proxy ببيانات اعتماد واحدة فقط.

تعامل مع استجابة الإنشاء باعتبارها حساسة. احفظ السر فورًا في مدير كلمات مرور أو مدير أسرار، ولا تكتب الاستجابة في السجلات. يجب ألا تعتمد العملاء على بقاء الأسرار النصية العادية قابلة للاسترجاع لاحقًا؛ فقد تعيد واجهات برمجة تطبيقات دورة الحياة قيمًا مقنّعة.

استخدم الحدود كضوابط لنطاق الضرر، وليس للميزانية وحدها

يكون limited_amount على مستوى بيانات الاعتماد مفيدًا لاحتواء مفتاح مسرّب أو عبء عمل خارج السيطرة، لكنه ليس سوى جزء واحد من حوكمة التكلفة.

التسلسل الهرمي المتين هو:

  • حد بيانات الاعتماد: الحد الأقصى للتعرض لعبء عمل واحد.
  • رصيد التطبيق: الحصة المتاحة لتطبيق الخدمة المشترك بها.
  • سياسة الرصيد العامة: احتياط اختياري لتطبيقات الدفع حسب الاستخدام المؤهلة.
  • تفويض السحب على المكشوف: تفويض منفصل للمنصة للقراءة فقط لا يمكن للعملاء تفعيله بأنفسهم.

لا تتعامل مع هذه على أنها متكافئة.

على سبيل المثال، حتى عندما يكون لدى تطبيق حصة متاحة، لا يزال بإمكان حد بيانات اعتماد فردية حظر عبء العمل. وعلى العكس، قد يتيح تمكين مشاركة الرصيد العام لتطبيق مؤهل الاستمرار بعد عدم كفاية رصيده الخاص—لكنه لا يزيل حدود بيانات الاعتماد أو التعطيل أو عمليات التحقق من انتهاء الصلاحية.

راقب الرصيد مع الوحدة والحالة

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

curl --fail-with-body \
  "https://platform.acedata.cloud/api/v1/applications/${APPLICATION_ID}" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

تشمل الحقول ذات الأهمية التشغيلية ما يلي:

  • remaining_amount — الحصة الحالية للتطبيق؛ تشير القيمة السالبة إلى حصة بانتظار التسوية.
  • used_amount — الاستخدام المتراكم المُبلّغ عنه للتطبيق.
  • service.unit — الوحدة، مثل Credit أو Count أو Token.
  • disabled — ما إذا كان التطبيق معطلاً.
  • expired_at — ما إذا كان وصول الاشتراك قد انتهت صلاحيته.
  • allow_overdraft — إشارة للقراءة فقط إلى سحب على المكشوف معتمد من المسؤول.

لا تفترض أبدًا أن المبلغ هو بالدولار الأمريكي. يجب تحديد عتبات التنبيه بوحدة الخدمة الفعلية.

لا يثبت الرصيد الإيجابي وحده التوافر. يجب أن يقيّم فحص الصحة لديك الرصيد وdisabled وانتهاء الصلاحية وحدود بيانات الاعتماد وحالة الخدمة. بالنسبة إلى خدمات Proxy، قد تتم تعليق مزامنة الرصيد أو تنتهي مهلتها، وفي هذه الحالة قد تتم إعادة أحدث رصيد محفوظ.

فحص Python موجز:

import os
import requests

minimum = float(os.getenv("MINIMUM_BALANCE", "10"))
url = f"https://platform.acedata.cloud/api/v1/applications/{os.environ['APPLICATION_ID']}"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}

response = requests.get(url, headers=headers, timeout=10)
response.raise_for_status()
application = response.json()

remaining = application.get("remaining_amount")
unit = application.get("service", {}).get("unit", "unknown")

if application.get("disabled"):
    raise RuntimeError("Application is disabled")
if application.get("expired_at"):
    print("Check whether the Application expiry has passed:", application["expired_at"])
if remaining is None:
    raise RuntimeError("No balance is available for this Application")
if not application.get("allow_overdraft", False) and float(remaining) < minimum:
    raise RuntimeError(f"Low balance: {remaining} {unit}")

بالنسبة إلى خدمات متعددة، اجلب قائمة التطبيقات مرة واحدة وقيّم كل عنصر محليًا بدلًا من استطلاع كل نقطة نهاية لتفاصيل التطبيق بتردد عالٍ.

قرر صراحةً ما إذا كانت مشاركة الرصيد العام مسموحة

يمكن تكوين تطبيقات الدفع حسب الاستخدام المؤهلة لاستخدام الرصيد العام للحساب عندما يكون رصيدها الخاص غير كافٍ:

curl -X POST \
  "https://platform.acedata.cloud/api/v1/applications/${APPLICATION_ID}/update-allow-consume-global/" \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"allow_consume_global": true}'

استخدم قيمة allow_consume_global المعادة باعتبارها مصدر الحقيقة. لا تفترض أنه تم حفظ القيمة المطلوبة.

قيود مهمة:

  • لا يمكن لتطبيقات Period استهلاك الرصيد العام؛ يحافظ الخادم على الحقل بقيمة false.
  • يلزم application_id مملوك ورمز حساب.
  • إذا كانت allow_overdraft=true، يمكن لتطبيق الدفع حسب الاستخدام متابعة الخصم من رصيده الخاص إلى ما دون الصفر ولن يتحول إلى الرصيد العام لمجرد أن رصيده الخاص غير كافٍ.
  • عند حدوث الاحتياط، يتحدد سلوك السحب على المكشوف بواسطة التطبيق العام الذي يدفع فعليًا.

يحسن الاحتياط العام الاستمرارية، لكنه يوسع أيضًا نطاق الضرر المالي. فعّله كسياسة متعمدة على مستوى الخدمة، وليس كوسيلة راحة افتراضية.

تتبع كل استدعاء إنتاج حسب بيانات الاعتماد

يحتفظ AceDataCloud بسجلات استدعاءات واجهة برمجة التطبيقات وملخصات الفوترة لأحدث 60 يومًا. يتم الاحتفاظ بنصوص الطلبات والاستجابات لمدة 30 يومًا؛ تحتفظ السجلات من الأيام 30–60 بالملخصات لكنها لم تعد تعيد نصوص metadata.request وmetadata.response الكاملة.

استعلم عن أحدث السجلات على:

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode "credential_id=${CREDENTIAL_ID}" \
  --data-urlencode 'perspective=both' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=-created_at' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

تشمل المرشحات المفيدة application_id وapi_id وcredential_id وstatus_code وحدود الوقت بتنسيق ISO 8601. تفصل معلمة perspective بين ثلاث وجهات نظر:

  • billing — الاستدعاءات المدفوعة بواسطة الحساب الحالي.
  • actor — الاستدعاءات التي بدأها الحساب الحالي فعليًا.
  • both — الاتحاد الافتراضي للاستدعاءات المدفوعة والمُبدأة. الحقول الأساسية للاستجابة للحوادث هي:
الحقل الاستخدام التشغيلي
credential_id تحديد عبء العمل المكشوف أو الذي به خلل
trace_id التحقيق في طلب واحد من البداية إلى النهاية
status_code الفصل بين الاستدعاءات الناجحة والفاشلة
elapsed تتبع زمن الاستجابة
used_amount الاستخدام المحسوب وفق القواعد الأصلية
original_amount الاستخدام قبل خصومات التطبيق
deducted_amount المبلغ النهائي الذي تم خصمه فعليًا
remaining_amount حصة التطبيق بعد الخصم
actor_user_id / user_id التمييز بين المستدعي والحساب المسؤول عن الدفع

بالنسبة للاستعلامات الكبيرة، استخدم نطاقات زمنية أقصر—ويُفضّل أن تكون يومًا واحدًا أو أقل—وأضف عوامل تصفية. إذا كان استعلام مطابق قيد التشغيل بالفعل، فقد تعيد واجهة برمجة التطبيقات 429 usage_query_in_progress؛ اتبع Retry-After مع تراجع تدريجي. إن 503 usage_query_timeout هي إشارة إلى تضييق الطلب بدلًا من تكراره فورًا.

أنشئ سير عمل للتدوير والحوادث قبل أن تحتاج إليه

دليل الاستجابة العملي هو:

  1. حدّد بيانات الاعتماد من سجل الاستخدام أو تكوين الخدمة.
  2. احتوِ التعرض عن طريق خفض حدها، أو تغيير انتهاء صلاحيتها، أو تضييق allowed_api_ids، أو إلغائها.
  3. دوّر السر وأحدّث مدير الأسرار.
  4. انشر القيمة الجديدة إلى عبء العمل دون تسجيلها في السجلات.
  5. تحقق من الاستدعاءات الناجحة ضمن معرّف بيانات الاعتماد المتوقع.
  6. راجع السجلات الأخيرة حسب بيانات الاعتماد، والحالة، وواجهة برمجة التطبيقات، ومعرّف التتبع.
  7. ألغِ بيانات الاعتماد المتقادمة بعد تأكيد اكتمال الانتقال.

أنشئ بيانات اعتماد منفصلة للتطوير، والمرحلة التجريبية، والإنتاج، والمهام المجدولة، والتكاملات مع الجهات الخارجية. هذا يجعل التدوير محليًا والإسناد واضحًا. إن مفتاح «إنتاج» مشتركًا واحدًا يزيد إلى أقصى حد من مخاطر الانقطاع وغموض التحقيق معًا.

خط أساس التحكم الموصى به

لكل عبء عمل في الإنتاج:

  • بيانات اعتماد API مخصصة؛ لا مشاركة بين البيئات.
  • اسم وصفي وبيانات تعريف الملكية.
  • قائمة سماح لواجهة برمجة التطبيقات تحتوي فقط على معرّفات نقاط النهاية المطلوبة.
  • حد استهلاك مستقل يتناسب مع عبء العمل المتوقع.
  • تاريخ انتهاء مع نافذة تجديد مخططة.
  • السر مخزن في مدير أسرار ومستبعد من السجلات.
  • تنبيه رصيد التطبيق بوحدة الخدمة الصحيحة.
  • فحوصات للتعطيل والانتهاء، وليس الرصيد وحده.
  • قرار صريح بشأن allow_consume_global.
  • لوحة معلومات الاستخدام مصفاة حسب التطبيق وبيانات الاعتماد.
  • معرّفات التتبع مُلتقطة في سجلات التطبيق.
  • إجراء موثق للتدوير والإلغاء.

الحوكمة هي حلقة

لا ينبغي إدارة إصدار بيانات الاعتماد، ومراقبة الرصيد، وتتبع الاستخدام كمهام منفصلة. فهي تشكل معًا حلقة تحكم مستمرة:

أصدر بشكل محدود → راقب التطبيق الدافع → تتبع الاستدعاءات الفعلية → دوّر أو ألغِ بسرعة.

تكشف واجهات برمجة التطبيقات الإدارية لـ AceDataCloud الحقول اللازمة لتنفيذ هذه الحلقة دون الخلط بين وصول الإدارة، ووصول وقت التشغيل، والحصة، وإسناد الفوترة. والنتيجة ليست مجرد مفتاح API أكثر أمانًا؛ بل هي نظام إنتاجي ذي تعرض محدود واستخدام قابل للتفسير.

الموارد الرسمية