انتقل إلى المحتوى

واجهة برمجة تطبيقات 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:

  1. في صفحة الوسوم في Control Panel، انقر على إنشاء وسم.
  2. أدخل اسم الوسم.
  3. في نوع القيمة، اختر كائن أو قائمة كائنات.
  4. ضمن الحقول، أدخل اسم الحقل الأول.
  5. اختر نوع الحقل.
  6. لإضافة حقل آخر، انقر على إضافة حقل.
  7. انقر على إنشاء.

في صفحة الـ tag، أضف حقلًا أو انقر على إزالة بجوار حقل لحذفه. لا يستطيع Control Panel إنشاء كائن متداخل أو قائمة متداخلة أو تغيير حقولهما. ويعرض الكائن المتداخل أو القائمة المتداخلة التي أُنشئت عبر الـ API كحقل واحد من نوع كائن أو قائمة كائنات. ويؤدي حذف هذا الحقل إلى حذفه مع كل ما بداخله.

إدارة المخطط

Anchor link to

أنشئ الـ object tags وعدّلها باستخدام أساليب REST أدناه. استخدم /json/1.3/addTag للـ tags العادية فقط، لأنه لا يستطيع تعريف الحقول.

عنوان URL الأساسي

Anchor link to
https://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 to

POST /api/tags

نص الطلب
Anchor link to
الاسمالنوعالوصف
name*stringاسم الـ object tag.
type*stringOBJECT لكائن واحد أو 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[].fieldsarrayحقول الكائن المتداخل أو القائمة المتداخلة، من 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 خاصة به. يُنشئ طلب واحد البنية بالكامل:

مثال: الـ tag profile من قسم الكائنات والقوائم المتداخلة
{
"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 to

POST /api/tags/{name}/fields

مثال: POST /api/tags/orders/fields
{
"field": { "name": "note", "type": "STRING" }
}

لإضافة حقل إلى كائن متداخل أو قائمة متداخلة، ضع اسمه الكامل في {name}، مثل POST /api/tags/profile.address/fields أو POST /api/tags/profile.visits/fields. ويمكن أن يكون الحقل الجديد كائنًا متداخلًا أو قائمة متداخلة مع fields خاصة به:

مثال: POST /api/tags/profile/fields
{
"field": {
"name": "company",
"type": "OBJECT",
"fields": [{ "name": "title", "type": "STRING" }]
}
}

يمكنك كتابة الحقل الجديد فورًا كجزء من قيمة الـ tag الكاملة. تفشل إضافة الحقل إذا كان الكائن يحتوي بالفعل على 20 حقلًا، أو إذا تجاوز الحقل حدًا آخر، أو إذا كان هناك tag موجود بالاسم الكامل للحقل، راجع الأخطاء.

حذف حقل

Anchor link to

DELETE /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الرسالةالسبب
400object tag and field names must contain only letters, digits and underscoresيحتوي الاسم على حرف آخر.
400<object>: an object needs 1 to 20 fieldsعند الإنشاء، لا يحتوي الـ tag أو الكائن المتداخل أو القائمة المتداخلة على حقول أو يحتوي على أكثر من 20 حقلًا.
400an object has at most 20 fieldsالكائن الذي تضيف إليه حقلًا يحتوي بالفعل على 20 حقلًا.
400<object>.<field>: objects nest at most 3 levels deepسيكون حقل OBJECT أو OBJECT_LIST في المستوى الرابع.
400an object tag holds at most 50 fields with values, nested ones includedسيحتوي الـ object tag على أكثر من 50 حقلًا ذا قيمة.
400field <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نوع حقل غير مدعوم.
400an object needs at least one field; delete the object insteadحاولت حذف آخر حقل في كائن.
400field is in use: ..., tag is in use: ...الحقل، أو شيء داخل الكائن المتداخل أو القائمة المتداخلة، أو الـ object tag مستخدم في الشرائح أو الـ In-Apps أو حملات Customer Journey أو عناصر أخرى.
403object tags are not enabled for the accountالـ object tags غير مُمكّنة للحساب.
403a device API token cannot call this method, use an account API tokenيستخدم الطلب رمز Device API.
404tag not foundGET أو DELETE /api/tags/{name}: لا يوجد tag بهذا الاسم، أو الاسم لحقل، أو الـ object tags غير مُمكّنة.
404object tag not found, field not foundأساليب الحقول: لا يوجد object tag أو كائن متداخل أو قائمة متداخلة أو حقل بهذا الاسم. ويُعيد {name} الذي يشير إلى حقل ذي قيمة أيضًا object tag not found.
409tag already existsيوجد tag باسم الـ object tag.
409tag <object>.<field> already existsيوجد tag بالاسم الكامل للحقل.

كتابة القيم

Anchor link to

اكتب قيم الـ object tags باستخدام /setTags و /bulkSetTags. تحتفظ هذه الأساليب بمصادقتها الخاصة: يأخذ /setTags رمز Device API في الترويسة Authorization: Token، ويأخذ /bulkSetTags رمز الوصول إلى API في auth. أرسل قيمة Object ككائن JSON، وقيمة ObjectList كمصفوفة من الكائنات:

مثال: /json/1.3/setTags
{
"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، وتأخذ القائمة المتداخلة مصفوفة من الكائنات:

مثال: قيم متداخلة في /json/1.3/setTags
"tags": {
"profile": {
"address": { "city": "Berlin", "geo": { "lat": "52.5" } },
"visits": [{ "code": "v1" }]
},
"orders": [
{ "sku": "A-1", "meta": { "color": "red" }, "lines": [{ "qty": 2 }, { "qty": 3 }] }
]
}

يأخذ كل حقل قيمة بتنسيق نوعه:

نوع الحقلمثال على القيمة
INTEGER120
STRING"paid"
LIST["gift", "express"]
DATE"2026-10-02 22:11" (UTC)، أو "2026-10-02"، أو طابع زمني Unix بالثواني
BOOLEANtrue أو false
PRICE19.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الاسم الكامل للحقل.
likestringإعادة القيم التي تحتوي على هذا النص فقط، في الموضع الذي يحدده like_op.
like_opstringSTARTS_WITH (افتراضي) أو ENDS_WITH أو CONTAINS.
order_bystringVALUE (افتراضي) أو COUNT.
order_directionstringASC (افتراضي) أو DESC.
limitintegerعدد القيم المراد إعادتها. القيمة الافتراضية 100.
offsetintegerعدد القيم المراد تخطيها.
pageintegerرقم الصفحة، بدءًا من 0. يُستخدم مع per_page بدلًا من limit و offset.
per_pageintegerعدد القيم في الصفحة.
مثال
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، تُصدَّر جميع حقوله، بما فيها المتداخلة.