> ## 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 للحساب الحالي مباشرةً بصيغة CSV، وهي مناسبة للتسوية المالية أو التحليل دون اتصال أو حفظ كميات كبيرة من السجلات. إذا كنت تحتاج فقط إلى عرض عدد قليل من التفاصيل في الصفحة، فاستخدم أولاً [قائمة سجلات الاستدعاء](https://platform.acedata.cloud/documents/platform-usage-list).

## التحضير

1. سجّل الدخول إلى [منصة AceDataCloud](https://platform.acedata.cloud).
2. أنشئ رمز الحساب في [وحدة تحكم Account Token](https://platform.acedata.cloud/console/platform-tokens)، واحفظه فوراً في مدير كلمات المرور أو Secret Manager.
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). لا يمكن استخدام رمز الحساب وCredential الخاص باستدعاء API للأعمال بالتبادل.

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

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

| العنصر | المحتوى |
| - | - |
| الطريقة | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/export/` |
| المصادقة | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (يمكن أن يتضمنه `platform:read` / `platform` بشكل موسع) |
| الاستجابة | `200 text/csv; charset=utf-8` |
| اسم الملف | `usages.csv` |

تعيد هذه الواجهة CSV بشكل متدفق ومتزامن، ولا تنشئ مهمة تصدير، ولا تعيد JSON أو رابط تنزيل. فقط عند عدم توفير وقتَي البداية والنهاية كليهما، يتم افتراض تصدير السجلات من بداية الشهر الميلادي الحالي حتى اللحظة الحالية؛ وعند توفير حد واحد فقط، لن يُستكمل الحد الآخر تلقائياً بحدود الشهر الحالي.

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

| المعامل | النوع | مطلوب | الافتراضي | الوصف |
| - | - | - | - | - |
| `perspective` | string | لا | `both` | `billing` أو `actor` أو `both` |
| `service_id` | UUID | لا | — | التصفية حسب الخدمة؛ يدعم تكرار المعامل |
| `application_id` | UUID | لا | — | التصفية حسب Application؛ يدعم تكرار المعامل |
| `api_id` | UUID | لا | — | التصفية حسب API؛ يدعم تكرار المعامل |
| `credential_id` | UUID | لا | — | التصفية حسب بيانات اعتماد API؛ يدعم تكرار المعامل |
| `status_code` | integer | لا | — | يدعم القيم المتكررة أو المفصولة بفواصل |
| `created_at_from` | datetime | لا | — | وقت البداية بتنسيق ISO 8601 |
| `created_at_to` | datetime | لا | — | وقت النهاية بتنسيق ISO 8601 |

يقتصر نطاق التصدير دائماً على السجلات المرئية للحساب الحالي بوصفه جهة الدفع و/أو المستدعي الفعلي، ولا يدعم التصدير عبر الحسابات.

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

احفظ CSV للشهر الحالي مباشرةً:

```shell theme={null}
curl --fail-with-body --location \
  'https://platform.acedata.cloud/api/v1/usage/apis/export/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  --output usages.csv
```

التصدير حسب Application والوقت ورمز الحالة:

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

curl --fail-with-body --get \
  'https://platform.acedata.cloud/api/v1/usage/apis/export/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'status_code=200,500' \
  --data-urlencode 'created_at_from=2026-09-01T00:00:00Z' \
  --data-urlencode 'created_at_to=2026-09-08T00:00:00Z' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  --output usages.csv
```

الحفظ المتدفق والتحقق من السلامة باستخدام Python:

```python theme={null}
import os
from pathlib import Path

import requests

url = "https://platform.acedata.cloud/api/v1/usage/apis/export/"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}
params = {
    "created_at_from": "2026-09-01T00:00:00Z",
    "created_at_to": "2026-09-08T00:00:00Z",
    "perspective": "both",
}
output = Path("usages.csv")

with requests.get(url, headers=headers, params=params, stream=True, timeout=120) as response:
    response.raise_for_status()
    if not response.headers.get("content-type", "").startswith("text/csv"):
        raise RuntimeError("服务器没有返回 CSV")
    with output.open("wb") as file:
        for chunk in response.iter_content(chunk_size=64 * 1024):
            file.write(chunk)

last_line = output.read_text(encoding="utf-8").splitlines()[-1]
if last_line.startswith("# truncated:") or last_line.startswith("# error:"):
    raise RuntimeError(f"导出不完整：{last_line}")
```

## أعمدة CSV

ترتيب رأس CSV ثابت كما يلي:

```text theme={null}
Usage ID,API,Status Code,Deducted Amount,Original Amount,Trace ID,Created At
```

| العمود | الوصف |
| - | - |
| `Usage ID` | معرّف سجل الاستدعاء |
| `API` | عنوان API؛ قد يكون معرّف API أو قيمة فارغة عند تعذر المطابقة |
| `Status Code` | رمز حالة HTTP |
| `Deducted Amount` | الحصة الفعلية المخصومة نهائياً |
| `Original Amount` | الحصة الأصلية قبل تطبيق الخصم |
| `Trace ID` | معرّف تتبع الطلب |
| `Created At` | وقت إنشاء السجل، بتنسيق ISO 8601 |

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

## تحديد ما إذا كان التصدير كاملاً

يمكن إخراج 1,000,000 سجل كحد أقصى في المرة الواحدة. بعد أن يبدأ الخادم في إرجاع CSV، لا يمكنه تغيير الخطأ الذي يحدث أثناء العملية إلى حالة HTTP أخرى، لذلك يجب على العميل فحص السطر الأخير:

* `# truncated:`: تم بلوغ حد عدد الصفوف؛ صدّر على دفعات باستخدام نوافذ زمنية أصغر.
* `# error:`: تمت مقاطعة القراءة المتدفقة؛ أعد التصدير بعد تقليص النطاق.

يجب أن يعتبر برنامج التسوية الملف غير مكتمل عند رؤية أي marker، ولا يجوز تسجيله بصمت.

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

| الحالة | طريقة المعالجة |
| - | - |
| `400 usage_history_expired` | استخدم `available_from` في الاستجابة للتعديل ضمن نطاق آخر 60 يوماً |
| `401 not_authenticated` | تحقق من أن Account Token موجود وصحيح ولم يُحذف |
| استجابة غير CSV | لا تحفظها كملف ناجح؛ اقرأ استجابة الخطأ أولاً وصحح الطلب |
| انقطاع التنزيل أو marker | قلّص النافذة الزمنية، واستخدم استراتيجية التراجع لإعادة التصدير |

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

* [عرض سجلات الاستدعاء](https://platform.acedata.cloud/documents/platform-usage-list): تصفية وتحديد موقع طلب واحد عبر الإنترنت.
* [تجميع حجم الاستدعاءات](https://platform.acedata.cloud/documents/platform-usage-aggregate): عرض البيانات المجمعة حسب التاريخ أو API أو النموذج.
* [عرض تفاصيل طلب الخدمة](https://platform.acedata.cloud/documents/platform-application-detail): التحقق من وحدة الحصة والحصة المتبقية.


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