> ## 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 التجارية للحساب الحالي خلال آخر 60 يومًا، وهي مناسبة لمطابقة الرسوم، وتحديد الطلبات الفاشلة، واستكشاف المشكلات حسب الخدمة أو Application أو API أو بيانات الاعتماد.

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

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

### 1. إنشاء رمز الحساب

تنتمي هذه الواجهة إلى API إدارة المنصة، ويجب استخدام **Account Token (رمز الحساب)**:

1. سجّل الدخول إلى [منصة AceDataCloud](https://platform.acedata.cloud).
2. افتح [وحدة تحكم Account Token](https://platform.acedata.cloud/console/platform-tokens).
3. انقر على «إنشاء»، واحفظ الرمز فورًا في مدير كلمات المرور أو Secret Manager.

للحصول على التعليمات الكاملة، راجع [إدارة رموز حساب منصة AceDataCloud](https://platform.acedata.cloud/documents/platform-token). يُستخدم رمز الحساب لـ `platform.acedata.cloud/api/v1/**`؛ بينما تستخدم واجهات الأعمال `api.acedata.cloud/**` بيانات اعتماد API (Credential)، ولا يمكن استخدامهما بالتبادل.

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
```

لا تكتب الرمز في كود الواجهة الأمامية أو السجلات أو المستودعات العامة؛ وإذا تم تسريبه، فاحذفه وأعد إنشاؤه فورًا من وحدة التحكم.

### 2. تجهيز معرّفات التصفية (اختياري)

يمكنك عرض السجلات التي يحق للحساب الحالي عرضها دون تمرير شروط تصفية. عند الحاجة إلى تضييق النطاق:

* `application_id`: احصل عليه من [قائمة طلبات الخدمة](https://platform.acedata.cloud/documents/platform-application-list)؛
* `credential_id`: احصل عليه من [قائمة بيانات اعتماد API](https://platform.acedata.cloud/documents/platform-credential-list)؛
* `api_id`: احصل عليه من [قائمة API](https://platform.acedata.cloud/documents/platform-api-list)؛
* `service_id`: احصل عليه من [قائمة الخدمات](https://platform.acedata.cloud/documents/platform-service-list).

لا يحتاج المستخدمون العاديون إلى تمرير `user_id`؛ وإذا تم تمريره صراحةً، فيجب أن يتطابق مع الحساب الحالي، وإلا فسيتم إرجاع `403`. يمكن للمسؤولين استخدام هذه المعلمة للتصفية عبر الحسابات.

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

| العنصر | المحتوى |
| - | - |
| الطريقة | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/` |
| المصادقة | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (يمكن أن يشملها `platform:read` / `platform`) |
| الترحيل إلى صفحات | `count` + `items`، الافتراضي 10 عناصر في كل صفحة |

## نطاق الاستعلام

| `perspective` | المعنى |
| - | - |
| `both` | القيمة الافتراضية؛ يعرض السجلات التي دفع الحساب الحالي رسومها أو استدعاها فعليًا |
| `billing` | يعرض فقط السجلات التي دفع الحساب الحالي رسومها |
| `actor` | يعرض فقط السجلات التي استدعاها الحساب الحالي فعليًا |

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

| المعلمة | النوع | مطلوب | الافتراضي | الوصف |
| - | - | - | - | - |
| `perspective` | string | لا | `both` | `billing` أو `actor` أو `both` |
| `user_id` | UUID | لا | — | للمسؤولين فقط للتصفية حسب المستخدم؛ يدعم تكرار المعلمة |
| `service_id` | UUID | لا | — | التصفية حسب الخدمة؛ يدعم تكرار المعلمة |
| `application_id` | UUID | لا | — | التصفية حسب Application؛ يدعم تكرار المعلمة |
| `api_id` | UUID | لا | — | التصفية حسب API؛ يدعم تكرار المعلمة |
| `credential_id` | UUID | لا | — | التصفية حسب بيانات اعتماد API؛ يدعم تكرار المعلمة |
| `status_code` | integer | لا | — | التصفية حسب رمز حالة HTTP؛ يدعم القيم المتكررة أو المفصولة بفواصل |
| `created_at_from` | datetime | لا | — | الحد الأدنى لوقت الإنشاء، ISO 8601 |
| `created_at_to` | datetime | لا | — | الحد الأعلى لوقت الإنشاء، ISO 8601 |
| `limit` | integer | لا | 10 | عدد العناصر في كل صفحة، بحد أقصى 100 |
| `offset` | integer | لا | 0 | إزاحة الترحيل إلى صفحات |
| `ordering` | string | لا | `-created_at` | ترتيب تنازلي حسب وقت الإنشاء |

عندما يكون وقت الطلب أقدم من آخر 60 يومًا، تُرجع الواجهة خطأ تحقق من الحقل `400`، موضحةً أن تفاصيل الاستدعاء الكاملة تُحتفظ بها لمدة 60 يومًا فقط.

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

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

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

التصفية حسب الوقت وApplication وحالة الفشل:

```shell theme={null}
export APPLICATION_ID='你的 Application ID'

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01T00:00:00Z' \
  --data-urlencode 'created_at_to=2026-09-02T00:00:00Z' \
  --data-urlencode 'status_code=500' \
  --data-urlencode 'limit=100' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

مثال ترحيل إلى صفحات في Python:

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

url = "https://platform.acedata.cloud/api/v1/usage/apis/"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}
params = {"perspective": "both", "limit": 100, "offset": 0}

response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()
data = response.json()

for usage in data["items"]:
    print(usage["created_at"], usage["status_code"], usage["deducted_amount"], usage["trace_id"])

if params["offset"] + len(data["items"]) < data["count"]:
    params["offset"] += len(data["items"])
```

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

```json theme={null}
{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "user_id": "00000000-0000-4000-8000-000000000002",
      "actor_user_id": "00000000-0000-4000-8000-000000000002",
      "application_id": "00000000-0000-4000-8000-000000000003",
      "api_id": "00000000-0000-4000-8000-000000000004",
      "credential_id": "00000000-0000-4000-8000-000000000005",
      "trace_id": "example-trace-id",
      "status_code": 200,
      "used_amount": 1.25,
      "original_amount": 1.25,
      "deducted_amount": 1.25,
      "remaining_amount": 98.75,
      "started_at": "2026-09-01T08:00:00Z",
      "finished_at": "2026-09-01T08:00:01Z",
      "elapsed": 1.0,
      "created_at": "2026-09-01T08:00:01Z",
      "updated_at": "2026-09-01T08:00:01Z",
      "metadata": {"model": "example-model"},
      "api": {"title": "Example API"},
      "service": {"id": "00000000-0000-4000-8000-000000000006", "title": "Example Service"},
      "credential": {"id": "00000000-0000-4000-8000-000000000005", "name": "Production"}
    }
  ]
}
```

## الحقول الرئيسية

| الحقل | الوصف |
| - | - |
| `user_id` | الحساب الذي يتحمل هذه الرسوم |
| `actor_user_id` | الحساب الذي بدأ الاستدعاء فعليًا؛ قد يختلف عن `user_id` عند تفويض الآخرين لاستخدام بيانات الاعتماد |
| `used_amount` | الاستخدام المحسوب لهذه المكالمة وفق القواعد الأصلية |
| `original_amount` | الاستخدام الأصلي قبل تطبيق خصم التطبيق |
| `deducted_amount` | الحصة المخصومة فعليًا بشكل نهائي |
| `remaining_amount` | الحصة المتبقية للتطبيق بعد إتمام هذه الرسوم |
| `elapsed` | مدة الاستدعاء المسجلة من جانب الخادم، بوحدة الثواني |
| `trace_id` | معرّف التتبع المستخدم عند فحص طلب واحد |
| `metadata` | بيانات وصفية عامة؛ لا تعرض القائمة محتوى الطلب أو الاستجابة الكامل |
| `api` / `service` / `credential` | ملخصات الكائنات المرتبطة لسهولة العرض؛ قد تكون فارغة إذا لم يعد الكائن المرتبط موجودًا |

يتم تحديد وحدة الحصة بواسطة `service.unit` الخاص بالتطبيق المقابل، ولا ينبغي افتراض أنها دولارات أمريكية.

## الأخطاء وإعادة المحاولة

| HTTP | `error` | المعنى | طريقة المعالجة |
| - | - | - | - |
| 400 | خطأ في التحقق من الحقول | نطاق الاستعلام أقدم من فترة الاحتفاظ البالغة 60 يومًا | اضبط وقت البدء ليكون ضمن آخر 60 يومًا |
| 401 | `not_authenticated` | رمز الحساب مفقود أو غير صالح | تحقق من Account Token، ولا تستخدم Credential الخاص بالأعمال بالخطأ |
| 403 | `permission_denied` | يتضمن الطلب سجلات غير مصرح بعرضها | أزل شروط تصفية المستخدمين غير المصرح بها |
| 429 | `usage_query_in_progress` | لا يزال الاستعلام المطابق تمامًا قيد التنفيذ | انتظر `Retry-After` ثم أعد المحاولة مع تراجع |
| 503 | `usage_query_timeout` | تجاوز الاستعلام الحد الزمني الآمن للخادم | قلّص النطاق الزمني أو أضف شروط تصفية ثم أعد المحاولة |

يُحتفظ بطلب واحد قيد التنفيذ كحد أقصى لمجموعة معلمات الاستعلام نفسها. بالنسبة للاستعلامات واسعة النطاق، استخدم أولوية نافذة يوم واحد أو أقل، ولا تكدس الطلبات المطابقة بفواصل زمنية ثابتة.

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

* [تجميع حجم الاستدعاءات](https://platform.acedata.cloud/documents/platform-usage-aggregate)：اعرض الاستخدام المُلخص حسب التاريخ وAPI.
* [تصدير حجم الاستدعاءات](https://platform.acedata.cloud/documents/platform-usage-export)：نزّل عددًا كبيرًا من التفاصيل مباشرةً بصيغة CSV.
* [عرض سجلات استدعاءات Proxy](https://platform.acedata.cloud/documents/platform-proxy-usage)：استعلم عن سجلات الخدمات من نوع Proxy.
* [عرض تفاصيل طلب الخدمة](https://platform.acedata.cloud/documents/platform-application-detail)：تحقق من الرصيد ووحدة الحصة.
* [تدوير بيانات اعتماد API](https://platform.acedata.cloud/documents/platform-credential-rotate)：استبدلها فورًا عند الاشتباه بتسرب بيانات الاعتماد.


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