جلب التفاعلات المجمّعة

المعلمات

الاستعلام

الاسم	النوع	مطلوب	الوصف	الافتراضي
tag	string	اختياري	Location tag to scope the rollup to. Defaults to `all`, every location the key can see. Omit it unless you tag locations.	all
siteUrls	string	اختياري	JSON-encoded array of publisher hostnames to include.	—
startDate	string	اختياري	Start of the date-range filter (YYYY-MM-DD).	—
endDate	string	اختياري	End of the date-range filter (YYYY-MM-DD).	—
searchString	string	اختياري	Full-text search across interaction content.	—
category	string	اختياري	Single interaction category, e.g. `REVIEW`.	—
categories	string	اختياري	JSON-encoded array of interaction categories.	—
ratingFilters	string	اختياري	JSON-encoded array of star ratings to include, e.g. `[3,4]`.	—
ratingFilter	integer	اختياري	Single star rating to filter by.	—
responseStatus	string	اختياري	JSON-encoded response-status filter. Values: `RESPONDED`, `PENDING`.	—
sortOrder	string	اختياري	JSON-encoded sort order. Values: `NEWEST_FIRST`, `OLDEST_FIRST`, `LAST_RESPONDED`.	—
first	integer	اختياري	Number of records to return from the beginning. Defaults to 20 when omitted, the endpoint always returns a single page, never the whole history.	—
after	string	اختياري	Cursor to page forward from. Pass `pageInfo.endCursor`, or equivalently the `cursor` of the last edge in the previous page.	—
last	integer	اختياري	Number of records to return from the end.	—
before	string	اختياري	Cursor to page backward from, used with `last`. Pass the `cursor` of the first edge of the page you are moving back from. `pageInfo` carries no `startCursor` field, so the edge cursor is the value to use.	—

الاستجابات

200Paginated rollup of interactions across the account. `data.rollupInteractions` holds the connection.

Response

{  "data": {    "rollupInteractions": {      "pageInfo": {        "hasNextPage": true,        "hasPreviousPage": false      },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "Excellent service, highly recommend.",            "authorName": "Priya S.",            "rating": 5,            "date": "2026-06-30T12:04:11+00:00",            "category": "Review",            "type": "Review",            "responded": false,            "responseCount": 0,            "canRespond": true,            "locationId": 1800289          },          "cursor": "SW50ZXJhY3Rpb246OWUyNmQyYTg="        }      ],      "totalCount": 1284    }  }}

401Unauthenticated, missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.

يعيد عرضًا للتفاعلات عبر مواقع الحساب. ويدعم التقسيم نفسه إلى صفحات باستخدام المؤشر (first، last، after، before) وعوامل التصفية نفسها التي تدعمها نقطة نهاية عرض قائمة التفاعلات الخاصة بكل موقع. يوجد الاتصال في data.rollupInteractions، ويحمل كل node قيمة locationId لتتمكن من إسناد التفاعل إلى متجره.

يمثل totalCount عدد التفاعلات المطابقة لعوامل التصفية عبر جميع المواقع المشمولة بالنطاق، وليس العدد الذي تعيده هذه الصفحة. يؤدي حذف first إلى إعادة 20 سجلًا، لذا لا يعيد استدعاء واحد كل تفاعلات الحساب السابقة أبدًا، وعليك التنقل بين الصفحات باستخدام after حتى تحصل على totalCount سجلًا.

تنبيه: يشمل التجميع دائمًا الحساب بأكمله

لا تحتوي نقطة النهاية هذه على معامل لتحديد موقع بعينه: عند استخدام القيمة الافتراضية tag=all، تجمع البيانات من كل موقع يمكن لمفتاح API الوصول إليه، والنطاق الأضيق الوحيد هو tag للمواقع. لا توجد وسيطة locationFilters أو locationIds، وإذا أرسلت إحداهما فستُتجاهل بدلًا من رفضها. ضيّق مجموعة النتائج باستخدام عوامل التصفية المتاحة (siteUrls، responseStatus، sortOrder، startDate/endDate، searchString)، أو جمّع النتائج بنفسك حسب قيمة locationId لكل عقدة.

حالة استخدام: قائمة انتظار «تحتاج إلى رد» على مستوى الحساب بأكمله

لسرد كل تقييم لا يزال ينتظر ردًا من المالك عبر جميع المواقع، استدعِ GET /rollup_interactions?responseStatus=["PENDING"]&sortOrder=["NEWEST_FIRST"]&first=50، ثم تنقّل بين الصفحات باستخدام after = pageInfo.endCursor (أو، بصورة مكافئة، قيمة cursor للحافة الأخيرة)، وتوقف عندما تكون قيمة hasNextPage هي false أو عندما تعيد إحدى الصفحات مصفوفة edges فارغة. يغني ذلك عن المرور على المواقع واحدًا تلو الآخر. ولأن النتائج مقسّمة إلى صفحات وتخضع الطلبات لحدود المعدل، التزم بالترويسة Retry-After عند تلقي 429، وفضّل عمليات التشغيل المقيّدة بنطاق زمني (startDate/endDate) لعمليات المزامنة المجدولة.