> ## 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.

# الحصول على سجلات استدعاء Proxy لمنصة AceDataCloud

> Platform API guide - Ace Data Cloud

استعلم عن سجلات الاستخدام للحساب الحالي ضمن خدمات نوع Proxy. لاستدعاءات API العادية، يُرجى استخدام [سجلات استدعاء API](https://platform.acedata.cloud/documents/platform-usage-list). إذا لم تكن متأكدًا من نوع الخدمة، يمكنك أولًا الاطلاع على `type` في [تفاصيل الخدمة](https://platform.acedata.cloud/documents/platform-service-detail).

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

1. سجّل الدخول إلى [منصة AceDataCloud](https://platform.acedata.cloud).
2. أنشئ رمز حساب في [وحدة تحكم Account Token](https://platform.acedata.cloud/console/platform-tokens)، واحفظه فورًا في مدير كلمات المرور أو Secret Manager.
3. افتح [صفحة الملف الشخصي](https://auth.acedata.cloud/user/profile) لنسخ UUID للحساب الحالي، واحفظه باسم `USER_ID`. يمكن أيضًا استخدام `user_id` في استجابة إنشاء رمز الحساب.
4. احصل على `application_id` لخدمة من نوع Proxy من [قائمة طلبات الخدمة](https://platform.acedata.cloud/documents/platform-application-list). عند الحاجة إلى التصفية حسب نقطة نهاية Proxy، احصل على `proxy_id` من [قائمة Proxy ضمن الخدمة](https://platform.acedata.cloud/documents/platform-service-proxies).

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

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
export USER_ID='你的账户 UUID'
export APPLICATION_ID='你的 Proxy Application ID'
```

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

| البند | المحتوى |
| - | - |
| الطريقة | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/proxies/` |
| المصادقة | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| Scope | `usage:read` |
| التقسيم إلى صفحات | `count` + `items`، 10 سجلات لكل صفحة افتراضيًا |

عندما يستعلم مالك Application باستخدام `application_id`، سيقوم الخادم أولًا بمزامنة السجلات المتاحة لذلك الـ Application، ثم يعيد القائمة، لذلك قد يكون وقت الاستجابة أطول من قائمة استخدام API العادية. يمكن للمستخدمين المصرح لهم قراءة السجلات المرئية الموجودة، لكن ذلك لن يؤدي إلى مزامنة من جانب المالك.

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

| المعامل | النوع | مطلوب | الافتراضي | الوصف |
| - | - | - | - | - |
| `user_id` | UUID | مطلوب للمستخدمين العاديين | — | UUID للحساب الحالي؛ سيؤدي تمرير حساب آخر إلى `403` |
| `application_id` | UUID | موصى به | — | التصفية حسب Proxy Application؛ يدعم المعاملات المتكررة |
| `proxy_id` | UUID | لا | — | التصفية حسب نقطة نهاية Proxy؛ يدعم المعاملات المتكررة |
| `limit` | integer | لا | 10 | عدد السجلات في كل صفحة، والحد الأقصى 100 |
| `offset` | integer | لا | 0 | إزاحة التقسيم إلى صفحات |
| `ordering` | string | لا | `-created_at` | ترتيب تنازلي حسب وقت الإنشاء |

لا تدعم الواجهة الحالية التصفية المباشرة حسب النموذج أو رمز حالة HTTP أو Credential أو نطاق زمني، كما لا تدعم معامل `perspective` الخاص بواجهة استخدام API. لا تضف هذه المعاملات غير المدعومة إلى الطلب وتفترض أنها أصبحت سارية.

## مثال على الطلب

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

مثال على التقسيم إلى صفحات في Python:

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

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/proxies/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "user_id": os.environ["USER_ID"],
        "application_id": os.environ["APPLICATION_ID"],
        "limit": 100,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

for usage in data["items"]:
    print(usage["created_at"], usage["deducted_amount"], usage["remaining_amount"])
```

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

```json theme={null}
{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "user_id": "00000000-0000-4000-8000-000000000002",
      "actor_user_id": null,
      "application_id": "00000000-0000-4000-8000-000000000003",
      "proxy_id": "00000000-0000-4000-8000-000000000004",
      "credential_id": null,
      "used_amount": null,
      "deducted_amount": 1.25,
      "remaining_amount": 98.75,
      "metadata": null,
      "created_at": "2026-09-01T08:00:00Z",
      "updated_at": "2026-09-01T08:00:00Z",
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "title": "Example Proxy Service"
      },
      "credential": null
    }
  ]
}
```

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

| الحقل | الوصف |
| - | - |
| `user_id` | الحساب الذي يتحمل هذه الرسوم |
| `actor_user_id` | المستدعي الفعلي؛ قد تكون السجلات القديمة فارغة |
| `application_id` | Proxy Application الذي أنشأ هذا السجل |
| `proxy_id` | نقطة نهاية Proxy المقابلة |
| `credential_id` | معرّف بيانات الاعتماد المرتبطة؛ قد تكون السجلات القديمة فارغة |
| `used_amount` | استخدام السجل الأصلي؛ قد يكون فارغًا |
| `deducted_amount` | الحصة المخصومة فعليًا بشكل نهائي |
| `remaining_amount` | الرصيد المتبقي لـ Application بعد الخصم |
| `metadata` | البيانات الوصفية العامة؛ قد تكون فارغة |
| `service` / `credential` | ملخص الكائن المرتبط لتسهيل العرض؛ قد يكون فارغًا عند عدم وجود الكائن المرتبط |

تُحدد وحدة الحصة بواسطة `service.unit` الخاص بـ Application المقابل.

## معالجة الأخطاء

| HTTP | المعنى | طريقة المعالجة |
| - | - | - |
| 401 | رمز الحساب مفقود أو غير صالح | تحقق من Account Token، ولا تستخدم Credential الخاص بالأعمال بالخطأ |
| 403 | لا تملك صلاحية عرض السجلات في الطلب | استخدم Application التابع للحساب الحالي، وأزل `user_id` غير المصرح به |
| 5xx | فشل مؤقت في المزامنة أو الاستعلام | احتفظ بشروط التصفية وأعد المحاولة بتراجع؛ عند استمرار الفشل، قدم Application ID والوقت لموظفي الدعم |

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

* [عرض سجلات استدعاء API](https://platform.acedata.cloud/documents/platform-usage-list): استعلم عن تفاصيل خدمات نوع API العادية.
* [الحصول على قائمة Proxy ضمن الخدمة](https://platform.acedata.cloud/documents/platform-service-proxies): احصل على `proxy_id`.
* [عرض تفاصيل طلب الخدمة](https://platform.acedata.cloud/documents/platform-application-detail): أكد الرصيد المتبقي والوحدة.


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