> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# الحصول على إحصاءات مجمّعة لاستخدام استدعاءات API في منصة AceDataCloud

> Platform API guide - Ace Data Cloud

لخّص عدد الطلبات والمقدار الفعلي المخصوم للحساب الحالي حسب التاريخ وAPI، وهو مناسب لإنشاء التقارير الشهرية ومخططات الاتجاهات وتحليل التكاليف. عند الحاجة إلى استكشاف الأخطاء لكل سجل على حدة، استخدم [قائمة سجلات الاستدعاء](https://platform.acedata.cloud/documents/platform-usage-list)، وعند الحاجة إلى تفاصيل كاملة دون اتصال، استخدم [تصدير حجم الاستدعاءات](https://platform.acedata.cloud/documents/platform-usage-export).

## الأعمال التحضيرية

1. سجّل الدخول إلى [منصة AceDataCloud](https://platform.acedata.cloud).
2. أنشئ رمز حساب في [وحدة تحكم Account Token](https://platform.acedata.cloud/console/platform-tokens)، واحفظه فورًا.
3. إذا كنت بحاجة إلى تضييق النطاق، احصل على المعرف المناسب من [قائمة طلبات الخدمة](https://platform.acedata.cloud/documents/platform-application-list)، أو [قائمة بيانات اعتماد API](https://platform.acedata.cloud/documents/platform-credential-list)، أو [قائمة API](https://platform.acedata.cloud/documents/platform-api-list).

للاطلاع على شرح كامل للرمز، راجع [إدارة رموز الحساب](https://platform.acedata.cloud/documents/platform-token). تستخدم هذه الواجهة Account Token، ولا تستخدم Credential الخاص بالأعمال.

```shell theme={null}
export PLATFORM_TOKEN='رمز حسابك'
```

## نظرة عامة على الواجهة

| البند | المحتوى |
| - | - |
| الطريقة | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/aggregate/` |
| المصادقة | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (يمكن أن يتضمنه `platform:read` / `platform`) |
| نطاق الصلاحيات | يُثبَّت المستخدم العادي على استخدامه المدفوع الخاص به؛ ويمكن للمسؤول تمرير `user_id` |
| | |

## معاملات الاستعلام

| المعامل | النوع | مطلوب | الافتراضي | الوصف |
| - | - | - | - | - |
| `created_at_from` | date / datetime | لا | أول يوم من الشهر الحالي في المنطقة الزمنية المحددة | وقت البداية، اسم المعامل الموصى به |
| `created_at_to` | date / datetime | لا | الوقت الحالي | وقت النهاية، اسم المعامل الموصى به |
| `timezone` | string | لا | `UTC` | منطقة زمنية IANA، مثل `Asia/Shanghai`؛ تعود القيم غير الصالحة إلى UTC |
| `service_id` | UUID | لا | — | التصفية حسب الخدمة؛ يدعم المعاملات المتكررة |
| `application_id` | UUID | لا | — | التصفية حسب Application؛ يدعم المعاملات المتكررة |
| `api_id` | UUID | لا | — | التصفية حسب API؛ يدعم المعاملات المتكررة |
| `credential_id` | UUID | لا | — | التصفية حسب بيانات اعتماد API؛ يدعم المعاملات المتكررة |
| `include_models` | boolean | لا | `false` | ما إذا كان سيتم حساب الملخص حسب بُعد النموذج بشكل إضافي؛ سيزيد تكلفة الاستعلام |
| `user_id` | UUID | لا | يُثبَّت المستخدم العادي على نفسه؛ وعند عدم تمريره من المسؤول يكون لجميع الحسابات | يمكن للمسؤول فقط تحديد أي حساب |

يمكن الاستمرار في استخدام `start_time` / `end_time` كأسماء مستعارة متوافقة مع العملاء القدامى، وتستخدم عمليات التكامل الجديدة بشكل موحّد `created_at_from` / `created_at_to`. تتضمن صيغة التاريخ لـ `created_at_to` ذلك اليوم التقويمي، أي يتم استخدام منتصف ليل اليوم التالي كحد فاصل.

## أمثلة على الطلبات

استعلم عن الملخص اليومي/API للشهر الحالي بتوقيت بكين، مع تضمين بُعد النموذج:

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  --data-urlencode 'include_models=true' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

استعلم عن استخدام أسبوع لـ Application محدد:

```shell theme={null}
export APPLICATION_ID='معرّف Application الخاص بك'

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01' \
  --data-urlencode 'created_at_to=2026-09-07' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

مثال Python:

```python theme={null}
import os
import requests

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/apis/aggregate/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "created_at_from": "2026-09-01",
        "created_at_to": "2026-09-07",
        "timezone": "Asia/Shanghai",
        "include_models": "true",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
print("requests:", data["requests"], "deducted:", data["total"])
for row in data["items"]:
    print(row["date"], row["api_id"], row["amount"])
```

## مثال على الاستجابة

```json theme={null}
{
  "items": [
    {
      "date": "2026-09-01",
      "api_id": "00000000-0000-4000-8000-000000000001",
      "amount": 12.5
    }
  ],
  "total": 12.5,
  "apis": {
    "00000000-0000-4000-8000-000000000001": {
      "title": "Example API"
    }
  },
  "requests": 42,
  "models": [
    {
      "model": "example-model",
      "amount": 12.5,
      "requests": 42
    }
  ]
}
```

## حقول الاستجابة

| الحقل | الوصف |
| - | - |
| `items` | مجمّعة حسب التاريخ في المنطقة الزمنية المحددة و`api_id`؛ يحتوي كل صف على `date` و`api_id` و`amount` |
| `total` | مجموع `deducted_amount` ضمن نطاق الاستعلام |
| `apis` | تعيين من معرّف API إلى ملخص العنوان، لتسهيل عرض `items` |
| `requests` | إجمالي عدد الطلبات ضمن نطاق الاستعلام |
| `models` | يُحسب فقط عند `include_models=true`؛ تحتوي كل خانة على `model` و`amount` و`requests` |

تعتمد وحدة الرصيد على `service.unit` الخاص بـ Application ذي الصلة. إذا تضمّن الاستعلام خدمات بوحدات مختلفة، فيرجى إجراء الإحصاءات بشكل منفصل حسب `service_id` أو `application_id` أولًا، لتجنب المقارنة المباشرة أو الجمع.

عندما لا يكون وقت النهاية أكبر من وقت البداية، تُرجع الواجهة بنية فارغة كاملة: `items=[]`، و`total=0`، و`apis={}`، و`requests=0`، و`models=[]`.

## اقتراحات الأخطاء والأداء

| HTTP | `error` | طريقة المعالجة |
| - | - | - |
| 400 | `usage_history_expired` | اضبط النطاق الزمني ليكون بعد `available_from` في الاستجابة |
| 401 | `not_authenticated` | تحقّق من Account Token، ولا تستخدم Credential الخاص بالأعمال بالخطأ |
| 403 | `permission_denied` | لا يمكن للمستخدمين العاديين الاستعلام عن حسابات أخرى |

* لا تفعّل `include_models` افتراضيًا؛ فعّله فقط عندما يحتاج التقرير فعلًا إلى تقسيم حسب النموذج.
* بالنسبة إلى الاستعلامات واسعة النطاق، أعطِ الأولوية للفصل حسب `service_id` أو `application_id`، لتجنب خلط الوحدات وتقليل تكلفة الاستعلام أيضًا.
* لا تُملأ التواريخ التي لا تحتوي على استدعاءات تلقائيًا بصفر؛ ينبغي للعميل إكمال محور التواريخ قبل الرسم.

## الخطوة التالية

* [عرض سجلات الاستدعاءات](https://platform.acedata.cloud/documents/platform-usage-list): تحديد التفاصيل التي تُكوّن النتيجة المجمّعة.
* [تصدير حجم الاستدعاءات](https://platform.acedata.cloud/documents/platform-usage-export): تنزيل تفاصيل CSV الكاملة.
* [عرض تفاصيل طلب الخدمة](https://platform.acedata.cloud/documents/platform-application-detail): تأكيد الرصيد والوحدة.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.