واجهة برمجة تطبيقات Object tags (تجريبي)
تخزن الـ object tags بيانات منظمة عن المستخدم في tag واحد. يحتوي الـ tag من نوع Object على كائن واحد بحقول مسماة، مثل آخر طلب order مع الحقلين amount و status. ويحتوي الـ tag من نوع ObjectList على مصفوفة من هذه الكائنات، مثل جميع الطلبات orders. ويمكن أن يكون الحقل نفسه كائنًا أو قائمة كائنات، مثل العنوان address ضمن profile. تُعرّف الحقول مرة واحدة، وتكتب القيم وتقرأها عبر واجهة برمجة تطبيقات الـ tags، وتنشئ الشرائح حسب قيم الحقول، وتُدرج القيم في الرسائل باستخدام Liquid.
كيف تعمل الـ object tags
Anchor link toللـ object tag مخطط وقيمة. المخطط هو اسم الـ tag وقائمة الحقول، ولكل حقل نوعه الخاص. تُخزَّن القيمة في الحقول، بشكل منفصل لكل مستخدم.
- الحقل. كل حقل هو tag باسم
<object>.<field>، مثلorder.amount. تنشئ الشرائح حسب الحقول، ويمكنك كتابة حقل من tag من نوعObjectبهذا الاسم. - قيمة
Object. كائن واحد لكل مستخدم، مثل"order": {"amount": 120, "status": "paid"}. - قيمة
ObjectList. مصفوفة من الكائنات بالحقول نفسها، مثل"orders": [{"amount": 120, "status": "paid"}, {"amount": 50}]. - الكائن المتداخل. حقل من نوع
OBJECTله حقوله الخاصة، مثلprofile.addressمع الحقلprofile.address.city. - القائمة المتداخلة. حقل من نوع
OBJECT_LIST، أي مصفوفة من الكائنات داخل object tag، مثلprofile.visits. راجع الكائنات والقوائم المتداخلة.
في الـ API، نوعا الـ tag والحقل هما OBJECT و OBJECT_LIST. وفي Control Panel هما كائن و قائمة كائنات. في هذه الصفحة، يُقصد بقائمة الكائنات الـ tag من نوع ObjectList أو القائمة المتداخلة.
الـ object tags دائمًا من نوع User-specific، أي أن القيمة تخص المستخدم وليس جهازًا واحدًا، وتُنسخ إلى جميع أجهزة المستخدم. للاطلاع على الـ tags العادية، راجع واجهة برمجة تطبيقات Tags.
الكائنات والقوائم المتداخلة
Anchor link toيمكن أن يحتوي حقل الـ object tag على حقوله الخاصة بدلًا من قيمة واحدة. يحتوي الكائن المتداخل، وهو حقل من نوع OBJECT، على كائن واحد. وتحتوي القائمة المتداخلة، وهي حقل من نوع OBJECT_LIST، على قائمة كائنات. ويمكن أن يحتوي عنصر القائمة أيضًا على كائنات متداخلة وقوائم متداخلة. يحتفظ كل حقل باسمه الكامل المفصول بالنقاط، مثل profile.address.city، وتنشئ الشرائح حسب هذه الأسماء.
على سبيل المثال، يمكن أن يكون للـ tag profile من نوع OBJECT والـ tag orders من نوع OBJECT_LIST البنية التالية:
profile OBJECT├── address OBJECT│ ├── city STRING│ └── geo OBJECT│ └── lat STRING└── visits OBJECT_LIST └── code STRING
orders OBJECT_LIST├── sku STRING├── meta OBJECT│ └── color STRING└── lines OBJECT_LIST └── qty INTEGERالحقول القابلة للبحث والحقول المخزنة فقط
Anchor link toيعتمد ما يمكنك فعله بالحقل على عدد قوائم الكائنات التي تعلوه:
- لا توجد قائمة فوق الحقل. يمكنك إنشاء شريحة حسب حقل مثل
profile.address.city، وكتابته بمفرده باسمه الكامل، واستخدامه في الرسائل. - قائمة واحدة فوق الحقل. يمكنك إنشاء شريحة حسب حقل مثل
profile.visits.codeأوorders.meta.colorواستخدامه في الرسائل. ولا تكتبه إلا كجزء من القائمة بالكامل. - قائمتان فوق الحقل. الحقل مثل
orders.lines.qtyمخزن فقط. استخدمه في الرسائل، وليس في الشرائح.
الحدود
Anchor link toيطبّق Pushwoosh هذه الحدود على الـ object tags، بما في ذلك الكائنات المتداخلة والقوائم المتداخلة:
| الحد | القيمة | عند تجاوزه |
|---|---|---|
| عمق التداخل | 3 مستويات من الكائنات والقوائم. الـ tag نفسه هو المستوى الأول، لذا فإن profile.address.geo هو أعمق كائن مسموح به | يُعيد أسلوب المخطط HTTP 400، راجع الأخطاء |
| عدد الحقول في كائن واحد | من 1 إلى 20، للـ tag ولكل كائن متداخل أو قائمة متداخلة | يُعيد أسلوب المخطط HTTP 400، راجع الأخطاء |
| عدد الحقول ذات القيم في object tag واحد | 50، بما في ذلك الحقول المتداخلة. لا تُحتسب الحقول من نوعي OBJECT و OBJECT_LIST | يُعيد أسلوب المخطط HTTP 400، راجع الأخطاء |
| الاسم الكامل للحقل | 64 حرفًا، مثل profile.address.city | يُعيد أسلوب المخطط HTTP 400، راجع الأخطاء |
| عدد العناصر في قائمة كائنات واحدة | 100، للـ tag ولكل قائمة متداخلة | تُرفض القيمة المكتوبة بالكامل |
| حجم القيمة المكتوبة الواحدة | 64 KB من JSON | تُرفض القيمة المكتوبة بالكامل |
تُعالَج القيمة المرفوضة بالطريقة نفسها التي تُعالَج بها قيمة ذات نوع حقل خاطئ، راجع الكتابة تستبدل القيمة بالكامل.
قواعد المخطط
Anchor link toيتحقق Pushwoosh من هذه القواعد عند إنشاء object tag أو إضافة حقل:
- تحتوي أسماء الكائنات والحقول على أحرف لاتينية وأرقام و
_فقط. - يحتوي الـ tag وكل كائن متداخل أو قائمة متداخلة على 1 إلى 20 حقلًا. وتنطبق الحدود الأخرى أيضًا. أسماء الحقول غير حساسة لحالة الأحرف، لذا فإن
Amountوamountهما الحقل نفسه. - يكون للحقل أحد هذه الأنواع:
INTEGER،STRING،LIST،DATE،BOOLEAN،PRICE،VERSION،OBJECT،OBJECT_LIST. يحتاج الحقل من نوعOBJECTأوOBJECT_LISTإلىfieldsخاصة به. حقول المنطقة الزمنية غير مدعومة. - لا يمكن أن يأخذ الحقل اسمًا يحمله tag آخر بالفعل. إذا كان الـ tag
order.noteموجودًا، تفشل إضافة الحقلnoteإلىorderبالخطأtag order.note already exists. - لا يمكن أن يفقد الكائن آخر حقل فيه. احذف الكائن بدلًا من ذلك.
- لا يمكن حذف حقل أو object tag قيد الاستخدام. يُعدّ الكائن المتداخل أو القائمة المتداخلة قيد الاستخدام عندما يكون أي شيء بداخله مستخدمًا. يسرد الخطأ أماكن الاستخدام، مثل
field is in use: segment Big buyers, in-app Spring sale. تُحتسب كاستخدامات: الشرائح، والـ In-Apps، وحملات Customer Journey الجارية، والـ presets، وقوالب البريد الإلكتروني، والعناصر الأخرى التي تشير إلى الـ tag.
إدارة الـ object tags في Control Panel
Anchor link toأنشئ object tag من دون كائنات متداخلة وقوائم متداخلة في Control Panel:
- في صفحة الوسوم في Control Panel، انقر على إنشاء وسم.
- أدخل اسم الوسم.
- في نوع القيمة، اختر كائن أو قائمة كائنات.
- ضمن الحقول، أدخل اسم الحقل الأول.
- اختر نوع الحقل.
- لإضافة حقل آخر، انقر على إضافة حقل.
- انقر على إنشاء.
في صفحة الـ tag، أضف حقلًا أو انقر على إزالة بجوار حقل لحذفه. لا يستطيع Control Panel إنشاء كائن متداخل أو قائمة متداخلة أو تغيير حقولهما. ويعرض الكائن المتداخل أو القائمة المتداخلة التي أُنشئت عبر الـ API كحقل واحد من نوع كائن أو قائمة كائنات. ويؤدي حذف هذا الحقل إلى حذفه مع كل ما بداخله.
إدارة المخطط
Anchor link toأنشئ الـ object tags وعدّلها باستخدام أساليب REST أدناه. استخدم /json/1.3/addTag للـ tags العادية فقط، لأنه لا يستطيع تعريف الحقول.
عنوان URL الأساسي
Anchor link tohttps://rpc-api.svc-nue.pushwoosh.comالمصادقة
Anchor link toيجب أن يتضمن كل طلب ترويسة Authorization تحتوي على رمز Server API الخاص بك. يحصل الطلب برمز Device API على HTTP 403 a device API token cannot call this method, use an account API token.
Authorization: Api YOUR_API_TOKENنقاط النهاية
Anchor link toتدير هذه الأساليب مخطط الـ object tags وتقرأ قيم حقولها:
| الأسلوب | المسار | الوصف |
|---|---|---|
POST | /api/tags | إنشاء object tag مع حقوله |
GET | /api/tags/{name} | الحصول على object tag مع حقوله |
GET | /api/tags | سرد الـ tags. يُعاد الـ object tag مع جميع fields الخاصة به، بما فيها المتداخلة، ولا تُسرد الحقول كـ tags منفصلة |
POST | /api/tags/{name}/fields | إضافة حقل إلى object tag أو كائن متداخل أو قائمة متداخلة |
DELETE | /api/tags/{name}/fields/{field} | حذف حقل أو كائن متداخل أو قائمة متداخلة |
DELETE | /api/tags/{name} | حذف object tag مع جميع حقوله |
GET | /api/tags:values | سرد القيم المخزنة لحقل، راجع القيم المخزنة لحقل |
يُعيد POST /api/tags الـ object tag، ويُعيد كلا أسلوبي الحقول الكائن المحدد في {name} بعد التغيير، ملفوفًا في {"tag": {...}}. ويُعيد DELETE /api/tags/{name} القيمة {}.
إذا لم تكن الـ object tags مُمكّنة لحسابك، يفشل POST /api/tags مع نوع كائن وكلا أسلوبي الحقول بالخطأ HTTP 403 object tags are not enabled for the account. ويُعيد GET /api/tags/{name} و DELETE /api/tags/{name} الخطأ HTTP 404 tag not found، ولا يسرد GET /api/tags الـ object tags. من دون تمكين الـ object tags لا يمكنك إنشاء أي منها، لذا لا يوجد ما تُكتب فيه القيم.
إنشاء object tag
Anchor link toPOST /api/tags
نص الطلب
Anchor link to| الاسم | النوع | الوصف |
|---|---|---|
| name* | string | اسم الـ object tag. |
| type* | string | OBJECT لكائن واحد أو OBJECT_LIST لقائمة كائنات. |
| fields* | array | حقول الكائن، من 1 إلى 20. |
| fields[].name* | string | اسم الحقل. يصبح الحقل الـ tag <name>.<fields[].name>. |
| fields[].type* | string | نوع الحقل: INTEGER أو STRING أو LIST أو DATE أو BOOLEAN أو PRICE أو VERSION أو OBJECT أو OBJECT_LIST. |
| fields[].fields | array | حقول الكائن المتداخل أو القائمة المتداخلة، من 1 إلى 20، بالتنسيق نفسه. مطلوبة للنوعين OBJECT و OBJECT_LIST ويتم تجاهلها للأنواع الأخرى. |
{ "name": "orders", "type": "OBJECT_LIST", "fields": [ { "name": "amount", "type": "INTEGER" }, { "name": "status", "type": "STRING" } ]}{ "tag": { "name": "orders", "type": "OBJECT_LIST", "system": false, "user_specific": true, "has_right_ace_modify": true, "fields": [ { "name": "amount", "type": "INTEGER", "fields": [] }, { "name": "status", "type": "STRING", "fields": [] } ] }}يُنشأ الـ tag من نوع User-specific بغض النظر عن قيمة user_specific. يُعيد GET /api/tags/{name} الكائن نفسه من دون الغلاف tag. تُرتَّب الحقول حسب الاسم، ويأتي الحقل الذي لا يحتوي على حقول متداخلة مع مصفوفة fields فارغة.
لإنشاء كائنات متداخلة وقوائم متداخلة، امنح الحقل النوع OBJECT أو OBJECT_LIST و fields خاصة به. يُنشئ طلب واحد البنية بالكامل:
{ "name": "profile", "type": "OBJECT", "fields": [ { "name": "address", "type": "OBJECT", "fields": [ { "name": "city", "type": "STRING" }, { "name": "geo", "type": "OBJECT", "fields": [{ "name": "lat", "type": "STRING" }] } ] }, { "name": "visits", "type": "OBJECT_LIST", "fields": [{ "name": "code", "type": "STRING" }] } ]}تُعاد الحقول المتداخلة بأسماء نسبية إلى كائنها، مثل city داخل address. يأخذ GET /api/tags/{name} اسم الـ tag نفسه فقط. ويُعيد الاسم المتداخل مثل profile.address الخطأ HTTP 404 tag not found.
إضافة حقل
Anchor link toPOST /api/tags/{name}/fields
{ "field": { "name": "note", "type": "STRING" }}لإضافة حقل إلى كائن متداخل أو قائمة متداخلة، ضع اسمه الكامل في {name}، مثل POST /api/tags/profile.address/fields أو POST /api/tags/profile.visits/fields. ويمكن أن يكون الحقل الجديد كائنًا متداخلًا أو قائمة متداخلة مع fields خاصة به:
{ "field": { "name": "company", "type": "OBJECT", "fields": [{ "name": "title", "type": "STRING" }] }}يمكنك كتابة الحقل الجديد فورًا كجزء من قيمة الـ tag الكاملة. تفشل إضافة الحقل إذا كان الكائن يحتوي بالفعل على 20 حقلًا، أو إذا تجاوز الحقل حدًا آخر، أو إذا كان هناك tag موجود بالاسم الكامل للحقل، راجع الأخطاء.
حذف حقل
Anchor link toDELETE /api/tags/{name}/fields/{field}
على سبيل المثال، يحذف DELETE /api/tags/orders/fields/note الحقل orders.note. لحذف حقل من كائن متداخل أو قائمة متداخلة، ضع اسمه الكامل في {name}: DELETE /api/tags/profile.address/fields/city.
يؤدي حذف كائن متداخل أو قائمة متداخلة إلى حذف كل ما بداخله: يحذف DELETE /api/tags/profile/fields/address أيضًا profile.address.city و profile.address.geo. لا يمكنك حذف آخر حقل في كائن، أو حقل أو كائن متداخل أو قائمة متداخلة قيد الاستخدام، راجع الأخطاء.
الأخطاء
Anchor link toتأتي الأخطاء بالتنسيق {"code": <n>, "message": "...", "details": [...]}. عند إنشاء object tag، تأتي رسالة الخطأ 400 بالشكل validate: rpc error: code = InvalidArgument desc = <message>، حيث <message> هو النص الوارد في الجدول. في هذه الرسائل، <object> هو الاسم الكامل للكائن، مثل profile.address.
| حالة HTTP | الرسالة | السبب |
|---|---|---|
| 400 | object tag and field names must contain only letters, digits and underscores | يحتوي الاسم على حرف آخر. |
| 400 | <object>: an object needs 1 to 20 fields | عند الإنشاء، لا يحتوي الـ tag أو الكائن المتداخل أو القائمة المتداخلة على حقول أو يحتوي على أكثر من 20 حقلًا. |
| 400 | an object has at most 20 fields | الكائن الذي تضيف إليه حقلًا يحتوي بالفعل على 20 حقلًا. |
| 400 | <object>.<field>: objects nest at most 3 levels deep | سيكون حقل OBJECT أو OBJECT_LIST في المستوى الرابع. |
| 400 | an object tag holds at most 50 fields with values, nested ones included | سيحتوي الـ object tag على أكثر من 50 حقلًا ذا قيمة. |
| 400 | field <name> is given twice | لحقلين الاسم نفسه، بغض النظر عن حالة الأحرف. |
| 400 | <object>.<field>: object and field names together cannot be longer than 64 characters | الاسم الكامل للحقل طويل جدًا. |
| 400 | <object>.<field>: field type must be INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT or OBJECT_LIST | نوع حقل غير مدعوم. |
| 400 | an object needs at least one field; delete the object instead | حاولت حذف آخر حقل في كائن. |
| 400 | field is in use: ..., tag is in use: ... | الحقل، أو شيء داخل الكائن المتداخل أو القائمة المتداخلة، أو الـ object tag مستخدم في الشرائح أو الـ In-Apps أو حملات Customer Journey أو عناصر أخرى. |
| 403 | object tags are not enabled for the account | الـ object tags غير مُمكّنة للحساب. |
| 403 | a device API token cannot call this method, use an account API token | يستخدم الطلب رمز Device API. |
| 404 | tag not found | GET أو DELETE /api/tags/{name}: لا يوجد tag بهذا الاسم، أو الاسم لحقل، أو الـ object tags غير مُمكّنة. |
| 404 | object tag not found, field not found | أساليب الحقول: لا يوجد object tag أو كائن متداخل أو قائمة متداخلة أو حقل بهذا الاسم. ويُعيد {name} الذي يشير إلى حقل ذي قيمة أيضًا object tag not found. |
| 409 | tag already exists | يوجد tag باسم الـ object tag. |
| 409 | tag <object>.<field> already exists | يوجد tag بالاسم الكامل للحقل. |
كتابة القيم
Anchor link toاكتب قيم الـ object tags باستخدام /setTags و /bulkSetTags. تحتفظ هذه الأساليب بمصادقتها الخاصة: يأخذ /setTags رمز Device API في الترويسة Authorization: Token، ويأخذ /bulkSetTags رمز الوصول إلى API في auth. أرسل قيمة Object ككائن JSON، وقيمة ObjectList كمصفوفة من الكائنات:
{ "request": { "application": "XXXXX-XXXXX", "userId": "user_42", "tags": { "order": { "amount": 120, "status": "paid" }, "orders": [ { "amount": 120, "status": "paid" }, { "amount": 50 } ] } }}إذا عيّنت القيمة حسب HWID، فإنها تُخزَّن لدى مستخدم ذلك الجهاز. ويكتب POST /api/devices:set_tags على عنوان URL الأساسي لأساليب المخطط الـ object tags بالقواعد نفسها. وتسرد استجابته حقول الكائنات بأسماء مسطحة مثل "profile.address.city".
يأخذ الكائن المتداخل كائن JSON، وتأخذ القائمة المتداخلة مصفوفة من الكائنات:
"tags": { "profile": { "address": { "city": "Berlin", "geo": { "lat": "52.5" } }, "visits": [{ "code": "v1" }] }, "orders": [ { "sku": "A-1", "meta": { "color": "red" }, "lines": [{ "qty": 2 }, { "qty": 3 }] } ]}يأخذ كل حقل قيمة بتنسيق نوعه:
| نوع الحقل | مثال على القيمة |
|---|---|
INTEGER | 120 |
STRING | "paid" |
LIST | ["gift", "express"] |
DATE | "2026-10-02 22:11" (UTC)، أو "2026-10-02"، أو طابع زمني Unix بالثواني |
BOOLEAN | true أو false |
PRICE | 19.95 |
VERSION | "1.0.0" |
الكتابة تستبدل القيمة بالكامل
Anchor link toتستبدل كل عملية كتابة القيمة المخزنة للـ object tag:
- يُحذف الحقل غير الموجود في القيمة الجديدة. ويُحذف أيضًا الحقل المُرسل بقيمة
null. - تحذف
nullأو[]أو""القيمة بالكامل. - تحذف
{}جميع حقول الـ tag من نوعObject. - يُتجاوز المفتاح الذي ليس حقلًا في الكائن.
- إذا لم تطابق قيمة حقل في أي مستوى نوع الحقل، تُرفض قيمة الـ tag بالكامل وتبقى القيمة المخزنة كما هي. ويحدث الشيء نفسه إذا تجاوزت القيمة حدًا: قائمة تضم أكثر من 100 عنصر أو أكثر من 64 KB من JSON.
لا يُبلغ /setTags عن القيمة المرفوضة في استجابته ويُعيد HTTP 200. تحقق من النتيجة باستخدام /getTags أو استخدم /bulkSetTags، الذي يُبلغ عن نتيجة لكل tag.
الحقول المخفية
Anchor link toالحقل المخفي هو حقل يضع عليه Pushwoosh علامة مخفي لاستخدامه الخاص. لا يمكنك إنشاء حقل أو إخفاؤه باستخدام أساليب المخطط في هذه الصفحة. لا يُعيد /getTags الحقول المخفية، لذا فإن القيمة التي تقرؤها وتعيد كتابتها لا تحتوي عليها أبدًا. ويعتمد ما يحدث لها عند الكتابة على النوع:
Object. يُحتفظ بالحقل المخفي غير الموجود في القيمة الجديدة، في أي مستوى. ويُحذف الكائن المتداخل المرئي غير الموجود في القيمة الجديدة مع كل ما بداخله، بما في ذلك الحقول المخفية. ويؤدي حذف القيمة بالكامل إلى حذف الحقول المخفية أيضًا.ObjectList. تستبدل كتابة القائمة جميع عناصرها، وتُفقد الحقول المخفية للعناصر القديمة. لا يملك العنصر معرّفًا، لذا لا يمكن مطابقة عنصر جديد مع عنصر قديم. وينطبق الأمر نفسه على القائمة المتداخلة.
كتابة جزء من Object
Anchor link toاكتب حقلًا واحدًا أو كائنًا متداخلًا أو قائمة متداخلة من tag من نوع Object باسمه الكامل بدلًا من قيمة الـ tag الكاملة. تعمل increment والعمليات الأخرى في /setTags على الحقول:
"tags": { "order.status": "shipped", "order.amount": { "operation": "increment", "value": 5 }}ويعمل الأمر نفسه مع حقل من كائن متداخل لا يعلوه سوى كائنات، مثل "profile.address.city": "Paris".
يمكن كتابة الكائن المتداخل أو القائمة المتداخلة التي لا يعلوها سوى كائنات بمفردها باسمها الكامل، مثل profile.address أو profile.visits. تستبدل القيمة هذا الجزء فقط، ويبقى باقي profile كما هو. وتُحتسب حدود الـ 100 عنصر والـ 64 KB من هذه القيمة:
"tags": { "profile.address": { "city": "Paris" }, "profile.visits": [{ "code": "v2" }]}لا يمكن كتابة أي شيء داخل قائمة كائنات بمفرده، لأنه ليس من الواضح أي عنصر يجب تغييره. يشمل ذلك حقل الـ tag من نوع ObjectList، مثل orders.sku، وكل ما داخل العنصر، مثل orders.meta أو profile.visits.code. يتجاوز /setTags مثل هذه القيمة. أرسل القائمة بالكامل بدلًا من ذلك.
لا تُنشأ الـ object tags تلقائيًا
Anchor link toتُتجاوز القيمة التي تحتوي على كائن أو مصفوفة كائنات لـ tag غير موجود. لا يُنشئ الإنشاء التلقائي للـ tags أي object tags، لذا أنشئ المخطط أولًا باستخدام POST /api/tags.
نتائج bulkSetTags
Anchor link toمع detailed=true، يُعيد حالة /bulkSetTags إحدى هذه النتائج للـ object tag، بالإضافة إلى ok و tag not found و wrong value. expect :<type>:
| النتيجة | السبب |
|---|---|
object tags are stored on the user only | الـ object tag ليس من نوع User-specific. |
cannot load the fields of the object | تعذّر على Pushwoosh قراءة حقول الـ object tag. |
wrong value. expect an object (a map) or, for a list of objects, an array of maps | القيمة لا تناسب الـ object tag، أو قيمة حقل في أي مستوى لا تطابق نوعه، أو تتجاوز القيمة حدًا. |
a field of a list of objects cannot be set on its own, set the whole list | تُعيَّن القيمة لشيء داخل قائمة كائنات، مثل orders.sku أو orders.meta. |
قراءة القيم
Anchor link toيُعيد /getTags قيمة Object ككائن JSON، وقيمة ObjectList كمصفوفة من الكائنات:
{ "status_code": 200, "status_message": "OK", "response": { "result": { "order": { "amount": 120, "status": "paid" }, "orders": [ { "amount": 120, "status": "paid" }, { "amount": 50 } ] } }}تُعاد الكائنات المتداخلة والقوائم المتداخلة في أي مستوى بالشكل نفسه الذي تكتبها به، مثل "profile": {"address": {"city": "Berlin"}, "visits": [{"code": "v1"}]}.
تُعاد قيم الحقول في /getTags بالطريقة نفسها التي تُعاد بها قيم الـ tags العادية: Date كطابع زمني Unix بالثواني، و Price كسلسلة نصية مثل "120.00"، و Boolean كـ 1 أو 0.
القيم المخزنة لحقل
Anchor link toيسرد GET /api/tags:values على عنوان URL الأساسي القيم المميزة التي يحملها الحقل، مع عدد المشتركين لكل قيمة. مرّر الاسم الكامل للحقل في name، مثل profile.address.city أو orders.sku.
معلمات الاستعلام
Anchor link to| الاسم | النوع | الوصف |
|---|---|---|
| application* | string | رمز التطبيق، XXXXX-XXXXX. |
| name* | string | الاسم الكامل للحقل. |
| like | string | إعادة القيم التي تحتوي على هذا النص فقط، في الموضع الذي يحدده like_op. |
| like_op | string | STARTS_WITH (افتراضي) أو ENDS_WITH أو CONTAINS. |
| order_by | string | VALUE (افتراضي) أو COUNT. |
| order_direction | string | ASC (افتراضي) أو DESC. |
| limit | integer | عدد القيم المراد إعادتها. القيمة الافتراضية 100. |
| offset | integer | عدد القيم المراد تخطيها. |
| page | integer | رقم الصفحة، بدءًا من 0. يُستخدم مع per_page بدلًا من limit و offset. |
| per_page | integer | عدد القيم في الصفحة. |
GET /api/tags:values?application=XXXXX-XXXXX&name=orders.sku&order_by=COUNT&order_direction=DESC{ "values": [ { "value": "A-1", "count": 120 }, { "value": "B-2", "count": 45 } ], "total": 2, "page": 0, "per_page": 100}لا تُعيد حقول Integer و Price أي قيم، كما هو الحال مع الـ tags العادية من هذين النوعين. ولا يملك الـ object tag أو الكائن المتداخل أو القائمة المتداخلة نفسه قيمًا خاصة به، لذا يُعيد اسمه HTTP 404 tag not found.
التقسيم إلى شرائح حسب الحقول
Anchor link toعيّن شروط الشريحة على الحقول، وليس على الـ object tag نفسه. في لغة التجزئة، الحقل هو tag باسم يحتوي على نقطة، ويأخذ عوامل نوعه الخاص:
AT("XXXXX-XXXXX", "order.amount", gte, 100)يأخذ حقل الكائن المتداخل أو القائمة المتداخلة اسمه الكامل، مثل profile.address.city أو profile.visits.code أو orders.meta.color. ويفشل الشرط على الـ object tag نفسه أو على كائن متداخل أو قائمة متداخلة، مثل profile.address، بالخطأ object tag has no value of its own, use one of its fields.
الحقل الذي تعلوه قائمتا كائنات، مثل orders.lines.qty، مخزن فقط. تُحفظ الشريحة التي تحتوي على مثل هذا الشرط، لكن حساب حجمها أو الإرسال إليها يفشل بالخطأ a field inside a list nested in a list is stored only and cannot be searched.
الشروط على ObjectList
Anchor link toيتطابق الشرط على حقل من tag من نوع ObjectList مع المستخدم عندما يستوفي عنصر واحد على الأقل من القائمة الشرط. يجب أن تتطابق الشروط على حقول القائمة نفسها المربوطة بـ AND مع العنصر نفسه:
AT("XXXXX-XXXXX", "orders.amount", gte, 100) * AT("XXXXX-XXXXX", "orders.status", eq, "paid")تضم هذه الشريحة المستخدمين الذين لديهم طلب واحد على الأقل تبلغ قيمته 100 أو أكثر ومدفوع في الوقت نفسه. لا يتطابق المستخدم الذي لديه طلب كبير غير مدفوع وطلب صغير مدفوع. ويُفحص العنصر نفسه لحقول الكائن الموجود داخله: يتطابق الشرطان orders.sku يساوي A-1 AND orders.meta.color يساوي red مع مستخدم لديه طلب واحد يحقق كليهما. لا يُشترط أن تتطابق الشروط المربوطة بـ OR مع العنصر نفسه. تُفحص الشروط على قائمتين مختلفتين لكل قائمة على حدة.
تعمل بعض العوامل بشكل مختلف على حقل من tag من نوع ObjectList:
notset. لا يحتوي أي عنصر في القائمة على قيمة في هذا الحقل. ويتطابق أيضًا المستخدم الذي ليس لديه القائمة.noteq. يحتوي عنصر واحد على الأقل على قيمة في هذا الحقل، وتختلف هذه القيمة عن القيمة المحددة. لا تُحتسب العناصر التي لا تحتوي على الحقل. يتطابق المستخدم الذي لديه طلبات بالحالتينpaidوnewمعnoteq "paid".notinعلى حقل من نوع List. لا يحتوي أي عنصر على أي من القيم المحددة.notinعلى حقل من نوع آخر. يحتوي عنصر واحد على الأقل على قيمة في هذا الحقل ليست من بين القيم المحددة.
لا يرتبط notset و notin على حقل من نوع List بالعنصر نفسه الذي ترتبط به الشروط الأخرى المربوطة بـ AND. وتنطبق هذه القواعد أيضًا على القوائم المتداخلة، مثل profile.visits.
استخدام القيم في الرسائل
Anchor link toأدرج حقول الـ object tags في الإشعارات الفورية ورسائل البريد الإلكتروني والرسائل النصية القصيرة SMS ورسائل تطبيقات المراسلة مثل WhatsApp باستخدام قوالب Liquid. لا تعمل Liquid إلا إذا كانت قوالب المحتوى مُمكّنة لحسابك. اكتب الحقل باسمه الكامل في أي مستوى:
Your city is {{ profile.address.city }}.خذ عنصرًا من قائمة كائنات حسب فهرسه، بدءًا من 0:
Your first order is {{ orders[0].sku }}, quantity {{ orders[0].lines[0].qty }}.يُعرض الفهرس الذي يتجاوز نهاية القائمة، أو القائمة التي لا يملكها المستخدم، كسلسلة نصية فارغة. تحقق من العنصر أولًا أو عيّن قيمة احتياطية باستخدام default:
{% if orders[0] %}Your first order is {{ orders[0].sku }}.{% endif %}Your first order is {{ orders[0].sku | default: "on its way" }}.كرّر المرور على قائمة كائنات، بما في ذلك قائمة داخل عنصر:
{% for o in orders %}{{ o.meta.color }}{% for l in o.lines %}{{ l.qty }}{% endfor %}{% endfor %}تعمل الحقول المخزنة فقط، مثل orders.lines.qty، في القوالب بالطريقة نفسها التي تعمل بها الحقول الأخرى.
تصدير الشرائح مع الـ object tags
Anchor link toيُصدّر /exportSegment حقول الـ object tags:
- CSV. كل حقل له قيمة هو عمود منفصل يحمل اسمه الكامل، مثل
order.amountأوprofile.address.city. ولا تحصل الـ object tags والكائنات المتداخلة والقوائم المتداخلة نفسها على عمود. يحتوي الحقل الموجود داخل قائمة كائنات، في أي مستوى، على القيم المميزة من جميع العناصر كمصفوفة JSON، بالطريقة نفسها التي يعمل بها tag من نوع List:["A-1","B-2"]. المصفوفة مرتبة ولا تُظهر العنصر الذي جاءت منه القيمة، لذا فهي لا تحافظ على ترتيب العناصر أيضًا. للحصول على العناصر كاملة، صدّر بتنسيقjsonأوjson_each_line. jsonوjson_each_line. تأتي الـ object tags متداخلة، بالشكل نفسه الذي يُعيدها به/getTags. الـ tag من نوعObjectهو إدخال واحد فيtagsمع حقوله تحتobject.fields، ويحمل الكائن المتداخل بداخله حقوله الخاصة تحتobject.fieldsأيضًا، في كل مستوى. والـ tag من نوعObjectListهو إدخال واحد مع عناصره فيobject_list.items، وكذلك القائمة المتداخلة. للحقول أسماء قصيرة، وهي مرتبة حسب الاسم، ويحمل كل حقل قيمته تحت مفتاح مسمى باسم النوع:integerأوstringأوlistأوdateأوbooleanأوpriceأوversion:
{ "name": "profile", "object": { "fields": [ { "name": "address", "object": { "fields": [{ "name": "city", "string": "Berlin" }] } }, { "name": "visits", "object_list": { "items": [{ "fields": [{ "name": "code", "string": "v1" }] }] } } ] }}يبدو الـ tag من نوع ObjectList على هذا النحو. تأتي قيم Integer كسلاسل نصية:
{ "name": "orders", "object_list": { "items": [ { "fields": [{ "name": "amount", "integer": "120" }, { "name": "status", "string": "paid" }] }, { "fields": [{ "name": "amount", "integer": "50" }] } ] }}يبدو العنصر الذي يحتوي على كائن متداخل وقائمة متداخلة هكذا:
{ "fields": [ { "name": "meta", "object": { "fields": [{ "name": "color", "string": "red" }] } }, { "name": "lines", "object_list": { "items": [{ "fields": [{ "name": "qty", "integer": "2" }] }] } } ]}إذا ذكر tagsList اسم object tag، تُصدَّر جميع حقوله، بما فيها المتداخلة.