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

# الحصول على قائمة وثائق منصة AceDataCloud

> Platform API guide - Ace Data Cloud

تعيد بشكل مُرقّم وثائق المطور المرئية للموقع الحالي، ويمكن استخدامها للبحث أو الفهرسة أو بناء التنقل في العميل بشكل مستقل. تحتوي القائمة حاليًا على `content` ومعلومات الأصل المتداخلة لكل وثيقة، وقد تكون الاستجابة كبيرة.

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

| البند | المحتوى |
| - | - |
| الطريقة | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/documents/` |
| المصادقة | عامة؛ لا يمكن لغير المسؤولين رؤية وثائق private |
| الترقيم | `count` + `items` |

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

| المعامل | النوع | مطلوب | الافتراضي | الوصف |
| - | - | - | - | - |
| `id` | UUID | لا | — | التصفية حسب معرّف الوثيقة؛ يدعم المعاملات المتكررة |
| `private` | boolean | لا | — | التصفية حسب حالة private؛ لا يزال غير المسؤولين غير قادرين على رؤية الوثائق الخاصة |
| `type` | string | لا | — | التصفية الدقيقة حسب قيمة `type` الفعلية لـ Document |
| `tag` | string | لا | — | التصفية حسب الوسم |
| `limit` | integer | لا | 10 | عدد العناصر في كل صفحة، بحد أقصى 100 |
| `offset` | integer | لا | 0 | إزاحة الترقيم |
| `ordering` | string | لا | `rank` | يدعم الترتيب حسب `rank` فقط؛ وتشير البادئة `-` إلى الترتيب التنازلي |

لا تدعم واجهة القائمة الحالية التصفية بواسطة `alias` أو `parent_id`. عند معرفة alias، استدعِ [تفاصيل الوثيقة](https://platform.acedata.cloud/documents/platform-document-detail) مباشرةً؛ وعند إنشاء تنقل شجري، اسحب الصفحات دفعةً واحدة ثم جمّعها في العميل باستخدام `parent.id` لكل عنصر.

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

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/documents/' \
  --data-urlencode 'tag=development' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=rank' \
  -H 'Accept: application/json'
```

```python theme={null}
import requests

response = requests.get(
    "https://platform.acedata.cloud/api/v1/documents/",
    params={"tag": "development", "limit": 100, "offset": 0},
    timeout=30,
)
response.raise_for_status()
data = response.json()
for document in data["items"]:
    parent = document.get("parent") or {}
    print(document["alias"], parent.get("alias"))
```

## بنية الاستجابة

```json theme={null}
{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "alias": "platform-token",
      "name": "Document of Platform Token",
      "title": "管理 AceDataCloud 平台账户令牌（Account Token）",
      "content": "# 管理 AceDataCloud 平台账户令牌……",
      "type": "Text",
      "private": false,
      "primary_only": false,
      "rank": 2400,
      "tags": [
        "development"
      ],
      "parent": {
        "id": "00000000-0000-4000-8000-000000000002",
        "alias": "platform",
        "title": "AceDataCloud 平台"
      },
      "sibling": null,
      "api_id": null,
      "proxy_id": null,
      "api_method": null,
      "metadata": null,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ]
}
```

تستخدم القائمة `DocumentIndexSerializer`، وتُرجع حاليًا حقول النموذج والعلاقات المتداخلة؛ وقد تحتوي وثائق API المرتبطة أيضًا على `api_method`. قد تُضاف الحقول بتوافق رجعي، وينبغي للعميل قراءتها حسب الحاجة. عند الحاجة إلى `children`، ولغة المحتوى المحللة، وتجزئة المحتوى، استخدم واجهة التفاصيل.

بالنسبة للسجلات العامة المرتبطة بوثائق المصدر، يوفر `content_source` معرّف وثيقة المصدر، وتجزئة محتوى المصدر، واللغة المطلوبة، ووقت تحديث الترجمة، وحالة `ready` أو `stale` أو `missing` أو `missing_source` أو `ambiguous`؛ ويكون هذا الحقل `null` للسجلات الأخرى. تتوافق `content_hash` عند `ready` مع ترجمة تلك اللغة. لا يزال النص يُعرض وفق القواعد الأصلية، بما في ذلك الرجوع إلى لغة بديلة عند فقدان الترجمة؛ ويجب على العملاء الذين يحتاجون إلى مزامنة الوثائق التحقق من الحالة والتجزئة معًا، ولا يمكنهم الحكم على اكتمال التحديث اعتمادًا على أن النص غير فارغ فقط.

## توصيات الاستخدام

* تحتوي الاستجابة على النص، لذا استخدم الترقيم واضبط مهلة معقولة عند المزامنة المجمعة، ولا تجلب الصفحة نفسها بالتوازي.
* alias هو المعرّف المستقر لعنوان URL للصفحة العامة؛ عند معرفة alias، اطلب `/api/v1/documents/{alias}` مباشرةً.
* لا يمكن للواجهة الحالية إجراء التصفية حسب الأصل على جانب الخادم؛ وعند إنشاء التنقل، جمّع حسب `parent.id` في العميل.

## الواجهات ذات الصلة

* [الحصول على تفاصيل وثيقة منصة AceDataCloud](https://platform.acedata.cloud/documents/platform-document-detail)
* [الحصول على تفاصيل API لمنصة AceDataCloud](https://platform.acedata.cloud/documents/platform-api-detail)


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