/v1 الغلاف نفسه وتعتمد طريقة ترقيم الصفحات نفسها:
قائمة على الرموز المميزة وللأمام فقط.
غلاف القائمة
string
دائمًا
"list".array
صفحة الموارد، بترتيب ثابت وحتمي.
string | null
مرّر هذه القيمة بوصفها
page_token في الطلب التالي لجلب الصفحة التالية.
تكون null عندما لا توجد نتائج أخرى.boolean
تشير إلى وجود نتائج إضافية بعد هذه الصفحة.
معلمات الطلب
integer
افتراضي:"25"
حجم الصفحة. عدد صحيح بين 1 و500. تؤدي القيم الواقعة خارج هذا النطاق إلى إرجاع
400 مع الرمز invalid_request.string
قيمة
next_page_token من الاستجابة السابقة. احذفها عند طلب الصفحة الأولى.استثناء: يعرض
GET /v1/cohorts/{id}/members 50 صفًا على الأكثر في كل
صفحة حتى عند طلب قيمة أعلى لـ limit. وتظل has_more و
next_page_token تعكسان الباقي الفعلي من المجموعة.apikey:secret أو secret:).
اضبط BASE على المضيف الإقليمي للمؤسسة — راجع
المناطق.
المرور على قائمة
حمّلLIVING_SECURITY_API_KEY من مدير الأسرار لديك كما في البدء السريع.
يتطلب هذا المثال entity:read؛ وقد يحتاج المفتاح المستخدم في دليل الطلب الأول
إلى هذا الإذن الإضافي. ثبّت requests لمثال Python أو jq لمثال الصدفة (shell).
يثبّت المثالان إصدارًا محددًا، ويُبقيان عوامل التصفية دون تغيير، ويرفضان
عمليات إعادة التوجيه. ويتوقفان عند حدوث الأخطاء وبعد 1,000 صفحة بدلًا من الإبلاغ عن
مرور جزئي على أنه مكتمل. يحدّ مهلة القراءة في Python فترة الخمول وليس المدة
الإجمالية للمهمة؛ لذا عيّن مهلة نهائية للمهمة في تكاملك.
اطلب الصفحات إلى أن تصبح قيمة next_page_token هي null. يُفضَّل استخدام limit=500 في عمليات
القراءة الكبيرة لتغطية المجموعة بعدد أقل من الطلبات — راجع
حدود المعدل.
حافظ على ثبات عوامل التصفية أثناء ترقيم الصفحات
رموز الصفحات هي مؤشرات معتمة وموقّعة. يرتبط كل رمز مميز بالمؤسسة، وحساب الخدمة الذي جرت مصادقته، وإصدار العقد، ومجموعة عوامل التصفية الدقيقة للطلب الذي أنتجه. يؤدي تغيير أي منها أثناء المرور — مثل إضافة عامل تصفيةtype في الصفحة الثانية — إلى إرجاع 400 مع الرمز
invalid_request على المعلمة page_token:
400 Invalid request
ترفض نقاط نهاية القوائم معلمات الاستعلام غير المدعومة بإرجاع
400
invalid_request يسمّي المعلمة. راجع مرجع كل نقطة نهاية لمعرفة
عوامل التصفية المدعومة فيها.التعامل مع مجموعة متقطعة أو متغيرة
لا تعيد هذه الأمثلة محاولة الطلبات تلقائيًا عند حدوث الأخطاء. بالنسبة إلى429، التزم بـ Retry-After
واتبع إرشادات إعادة المحاولة المحدودة. احتفظ بالمنطقة
وحساب الخدمة والإصدار وعوامل التصفية نفسها، وبآخر رمز صفحة جرت معالجته بنجاح عند إعادة محاولة
عملية قراءة. إن تغيير بيانات الاعتماد لا يمنح صلاحية وصول:
إذ يتحقق كل طلب من الأذونات الحالية.
القراءة متعددة الصفحات ليست لقطة ثابتة للمجموعة. فقد تتغير الصفوف أثناء
المرور عليها. عالج الموارد بحسب id الثابت الخاص بها واجعل عمليات
الكتابة اللاحقة متماثلة الأثر (idempotent)؛ فقد تعيد إعادة التشغيل صفًا مرة أخرى. إذا رُفض رمز مميز،
فافحص الخطأ page_token وصحّح الطلب قبل إعادة البدء من
الصفحة الأولى. لا تتجاهل البيانات التي سبقت معالجتها بصمت ولا تعتبر
عملية تصدير متقطعة مكتملة. وللحصول على إجماليات دقيقة للتقارير، استخدم
مورد التقارير المناسب بدلًا من اعتبار المرور الحي على القائمة لقطة ثابتة.
