الجماهير
`audiences.list` و`get` و`create` و`update` و`delete` و`empty` و`growth` و`list_contacts` و`add_contact` و`add_contacts` و`import_contacts` و`remove_contact` و`remove_contacts`.
كل الدوالّ
audiences = client.audiences.list_alleveryone = audiences.find { |audience| audience[:builtin] == "default" } list = client.audiences.create( name: "Product updates", description: "Customers who asked to hear about releases") client.contacts.create(email: "[email protected]", name: "Grace Hopper")client.audiences.add_contact(list[:id], email: "[email protected]") bulk = client.audiences.add_contacts(list[:id], emails: ["[email protected]", "[email protected]"]) imported = client.audiences.import_contacts( list[:id], contacts: [{email: "[email protected]", name: "Katherine Johnson"}]) members = client.audiences.list_all_contacts(list[:id], q: "grace", sort: "added-newest", limit: 200) growth = client.audiences.growth(audience_ids: [list[:id]], days: 30) client.audiences.update(list[:id], name: "Release notes")client.audiences.remove_contact(list[:id], "[email protected]")client.audiences.remove_contacts(list[:id], emails: ["[email protected]"])client.audiences.empty(list[:id])client.audiences.delete(list[:id]) puts everyone[:contactCount] if everyoneputs bulk[:missing], imported[:created], members.size, growth.dig(:totals, :added)الجمهور قائمة مسمّاة من جهات الاتصال في مساحة العمل هذه. وكل جهة اتصال تكون في الجمهور الافتراضي المدمج منذ لحظة وجودها، وbuiltin هو ما يسمّي ذلك الصف. وما عداه لك أن تنشئه وتملأه وتحذفه. فرّع على builtin لا على الاسم الذي يستطيع أي أحد تغييره.
الاستدعاء على جمهور واحد يأخذ معرّفه كأول وسيط، ويأخذ remove_contact العنوان كوسيط ثانٍ. وكل ما عدا ذلك وسائط مسمّاة في Ruby، ويمكن أيضًا تمرير متن الطلب في Hash واحد. وخيارات growth وlist_contacts بصيغة snake_case (audience_ids: وoffset_minutes:)، بينما تحتفظ حقول المتن بأسماء API (emails: وcontacts:). والاستجابة Hash بمفاتيح من نوع Symbol بصيغة camelCase الخاصة بـ API، فيقرأ audience[:contactCount] العدد.
أرسل إلى جمهور أو أكثر عبر client.broadcasts.send، الموضّح في صفحة البث. ووضع جهة اتصال في جمهور هو كتابة على الجمهور لا على جهة الاتصال، لذا فإن audiences:write هو النطاق الوحيد الذي يُتحقق منه. والاستثناء هو import_contacts. فهو ينشئ جهات اتصال، لذا يحتاج إلى contacts:write أيضًا.
يقبل add_contact عنوانًا هو جهة اتصال أصلًا ويرفض ما ليس كذلك، بالخطأ 422 contact_not_found، يُرفع في صورة OpenEmail::ValidationError. احفظه أولًا عبر client.contacts.create. وإضافة شخص مرتين تجيب بالعضوية القائمة أصلًا حاملةً addedAt الأصلي، فالاستدعاء آمن لإعادة المحاولة، ويعيد الـ gem محاولته بعد فشل في الشبكة.
يمكن إعادة تسمية الجمهور الافتراضي ووصفه كأي جمهور آخر، لكن لا يمكن حذفه ولا تقليصه. ويُرفض الأمران بالخطأ 409 audience_immutable، يُرفع في صورة OpenEmail::ConflictError تكون قيمة conflict? فيه true. احذف جهة الاتصال حين تقصد أن تذهب جهة الاتصال نفسها.
الاستجابة: جمهور
يعيد list صفحة واحدة منها في صورة OpenEmail::Page، مع items وhas_more? وnext_cursor، والجمهور الافتراضي أولًا ثم الباقي من الأحدث. وتحمل الصفحة 25 ما لم يطلب limit: حتى 100. ويعيد list_all كل الصفحات في Array واحدة، ويمرّر iterate جمهورًا واحدًا في كل مرة إلى كتلة، أو يعيد Enumerator دونها. ويعيد كلٌّ من get وcreate وupdate جمهورًا واحدًا. أما list_contacts فيعيد بدلًا من ذلك صفحة من جهات الاتصال، أي جهات الاتصال نفسها مع تاريخ انضمام كل منها لا سجلات عضوية، ومعه list_all_contacts وiterate_contacts.
idString- المقبض الدائم، `aud_` يليه 24 حرفاً ست عشرياً. الأسماء ليست فريدة، فهذا ما ينتمي إلى الإعدادات المخزَّنة.
nameString- يُقلَّم عند الكتابة، من 1 إلى 120 حرفاً. ويجوز أن يتشارك جمهوران اسماً واحداً، لأن الجمهور يُعنوَن بمعرّفه.
descriptionString or nil- نص حر لمن يقرأ القائمة لاحقًا. ويكون nil حين لم يكتب أحد شيئًا، و`description: nil` في `update` يمسحه.
builtinString or nil- القيمة `default` على صف واحد بالضبط في كل مساحة عمل، وهو الجمهور الذي يحمل كل جهات الاتصال، وnil على كل جمهور أنشأه شخص. قارنها بـ `"default"` بدل التحقق من أنها nil، كي لا يُحسب جمهور مدمج يُضاف لاحقًا على أنه الجمهور الافتراضي.
contactCountInteger- كم جهة اتصال في الجمهور، محسوبةً لحظة القراءة لا مأخوذة من ذاكرة مؤقتة. وقراءتان على جانبي `contacts.create` تختلفان بواحدة.
lastContactAtString or nil- بصيغة ISO 8601 بتوقيت UTC، متى انضمت آخر جهة اتصال إلى هذا الجمهور. ويكون nil ما دام الجمهور فارغًا.
createdAtString- بصيغة ISO 8601 بتوقيت UTC، متى أُنشئ الجمهور. وهو يحدد ترتيب القائمة بعد الجمهور الافتراضي.
updatedAtString- بصيغة ISO 8601 بتوقيت UTC، ويُحدَّث بإعادة التسمية أو تغيير الوصف. ولا تمسّه تغييرات العضوية.
المعاملات: audiences.list_contacts
limitInteger- كم جهة اتصال في كل صفحة، عدد صحيح من 1 إلى 200، والافتراضي 50.
cursorString- `next_cursor` من الصفحة السابقة، يُرسَل مع `q:` و`source:` و`sort:` و`statuses:` نفسها. والمؤشر الذي يسمّي جهة اتصال ليست في هذا الجمهور يعطي 400 `invalid_cursor`، يُرفع في صورة `OpenEmail::InvalidRequestError`.
qString- يبحث في الاسم والعنوان، حتى 200 حرف. وإن لم يطابق شيء تمامًا في الصفحة الأولى، تُعاد تهجئات قريبة بدلًا من ذلك، وتواصل الصفحات التالية المطابقة بالطريقة نفسها.
sourceString- `manual` لجهات الاتصال التي حفظها شخص عمدًا، و`auto` لتلك التي سجّلها محرّر الرسائل في التطبيق. اتركه للحصول على كل من في الجمهور.
sortString- يتبع `last-heard-newest` (الافتراضي) و`last-heard-oldest` قيمة `lastSeenAt`، وتأتي جهات الاتصال التي لم تُراسَل قط في الآخر في الأول وفي البداية في الثاني. ويتبع `added-newest` و`added-oldest` وقت انضمام كل جهة اتصال إلى هذا الجمهور، ويتجاهل `name` حالة الأحرف ويرتّب جهة الاتصال التي بلا اسم بحسب عنوانها.
statusesArray<String>- يُبقي `["subscribed"]` الأعضاء الذين لم يلغوا اشتراكهم و`["unsubscribed"]` الذين ألغوه. اتركه، أو مرّر Array فارغة، أو اذكر القيمتين، للحصول على كل من في الجمهور. ويحتوي `OpenEmail::AUDIENCE_MEMBER_STATUSES` على القيم، ويرسلها الـ gem مضمومة بفواصل بوصفها معامل الاستعلام `status`.
الاستجابة: جهة اتصال في جمهور
يعيد list_contacts صفحة OpenEmail::Page من جهات اتصال في صورة Hash، ويمر list_all_contacts وiterate_contacts على كل الصفحات بالوسائط المسمّاة نفسها. وكل صف جهة اتصال بالشكل الذي يعيده contacts.list، وحقولها مشروحة في صفحة جهات الاتصال، مع حقلين إضافيين. والمرور على كل الصفحات هو طريقة تصدير الجمهور.
addedAtString- بصيغة ISO 8601 بتوقيت UTC، متى انضمت جهة الاتصال إلى هذا الجمهور. وإخراج جهة اتصال ثم إضافتها مجددًا يبدأ عدّها من جديد.
unsubscribedAtString or nil- بصيغة ISO 8601 بتوقيت UTC، متى ألغت جهة الاتصال اشتراكها من بث أُرسل إلى هذا الجمهور، أو nil ما دامت مشتركة. وجهة الاتصال التي ألغت اشتراكها تبقى في الجمهور، ويتخطاها البث الموجّه إليه. وإخراجها ثم إضافتها مجددًا يجعلها مشتركة من جديد.
الإضافة والإزالة دفعة واحدة
يأخذ add_contacts وremove_contacts الوسيط emails:، وهو Array من 1 إلى 200 عنوان، ويغيّران جمهورًا واحدًا بطلب واحد. ولا ينشئ add_contacts جهة اتصال أبدًا. فالعنوان الذي ليس جهة اتصال يعود في missing، وimport_contacts هو الاستدعاء الذي ينشئها. وكلاهما آمن للتكرار، فيعيد الـ gem محاولتهما بعد فشل في الشبكة، وإعادة المحاولة تبلّغ عن الأشخاص أنفسهم بوصفهم منجزين أصلًا بدل أن تفشل.
الإضافة إلى الجمهور الافتراضي تجيب بـ added: 0، لأن كل جهة اتصال فيه أصلًا، وremove_contacts عليه يُرفض بالخطأ 409 audience_immutable. وإخراج شخص من جمهور يُبقيه في دفتر العناوين وفي الجمهور الافتراضي وفي جماهيره الأخرى.
audienceIdString- الجمهور الذي غيّره الاستدعاء، في النتيجتين كلتيهما.
addedInteger- في نتيجة `add_contacts`: العضويات الجديدة التي أنشأها هذا الاستدعاء.
unchangedInteger- في نتيجة `add_contacts`: جهات الاتصال التي كانت في الجمهور أصلًا. ولم يُكتب لها شيء.
removedInteger- في نتيجة `remove_contacts`: العضويات التي أزالها هذا الاستدعاء.
notInAudienceArray<String>- في نتيجة `remove_contacts`: جهات الاتصال التي لم تكن في الجمهور، فلم يحدث لها شيء.
missingArray<String>- في كلتيهما: العناوين التي ليست جهات اتصال في مساحة العمل هذه، بأحرف صغيرة ومن دون تكرار.
الاستيراد
import_contacts هو استيراد CSV في صفحة الجمهور. يأخذ contacts:، وهو Array من 1 إلى 500 Hash، لكل منها email وname اختياري. وكل عنوان سليم الصياغة يصبح جهة اتصال إن لم يكن كذلك بعد، وينتهي الجميع في الجمهور. أرسل القائمة الأطول على عدة استدعاءات. ويتطلب audiences:write وcontacts:write، والمفتاح الذي ينقصه أحدهما يُرفض بالخطأ 403 insufficient_scope، حيث تكون قيمة scope_missing? في الخطأ true.
العنوان الذي هو جهة اتصال أصلًا يُعاد استخدامه ويحتفظ باسمه، وname هنا لا يملأ إلا اسمًا كان فارغًا. وتُحفظ جهة الاتصال الجديدة بوصفها manual وتنضم إلى الجمهور الافتراضي أيضًا، والعنوان الذي حُذف من دفتر العناوين يعود. وإعادة إرسال الصفوف نفسها لا تنشئ شيئًا مرتين، فيعيد الـ gem محاولة الاستدعاء بعد فشل في الشبكة.
audienceIdString- الجمهور الذي ذهبت إليه الصفوف.
createdInteger- جهات الاتصال الجديدة التي حفظها هذا الاستدعاء.
addedInteger- العضويات الجديدة في هذا الجمهور، بما فيها جهات الاتصال التي كانت موجودة ولم تكن فيه بعد.
skippedInteger- الصفوف التي لم تُستورد لأن العنوان كان غير سليم.
invalidArray<String>- العناوين غير السليمة، كما أُرسلت تمامًا.
الإفراغ
يُخرج empty(id) كل جهة اتصال من جمهور واحد بطلب واحد ويعيد الجمهور كما هو الآن، مع contactCount بقيمة 0، مضافًا إليه removed، أي عدد العضويات المُزالة. ويحتفظ الجمهور بمعرّفه واسمه ووصفه، وتبقى كل جهة اتصال في دفتر العناوين وفي جماهيرها الأخرى.
لا يمكن التراجع عن ذلك، ولا شيء يسجّل مَن كان في القائمة، لذا مرّ على list_all_contacts أولًا إن كنت قد تريد استعادتها. ولا يمكن إفراغ الجمهور الافتراضي، ويُرفض الاستدعاء بالخطأ 409 audience_immutable. ولا يعيد الـ gem محاولة empty بعد فشل في الشبكة، لأن الاستدعاء الثاني ينجح مع removed: 0. وإن ضاعت استجابة، فاقرأ الجمهور عبر get.
النمو
يقرأ growth كم جهة اتصال انضمت إلى كل جمهور خلال نافذة تنتهي الآن، وكم منها ألغى اشتراكه داخلها، باليوم أو الساعة أو الدقيقة. وهو المخطط في صفحة الجماهير. يأخذ وسائط مسمّاة، ويتطلب audiences:read، ويعيد Hash واحدًا.
growth = client.audiences.growth( audience_ids: ["aud_9f2c4b7e1a0d63d84c5f2e7b"], days: 90, grain: "day", offset_minutes: Time.now.utc_offset / 60) puts "#{growth.dig(:totals, :added)} joins since #{growth[:since]}" growth[:series].each do |series| puts "#{series[:name]}: #{series[:before]} before the window, #{series[:total]} now"endيسجّل الجمهور متى انضم شخص ما ولا يسجّل أبدًا متى غادر، لذا فكل رقم يعدّ الأشخاص الذين ما زالوا في القائمة اليوم بحسب تاريخ انضمامهم، ولا ينخفض أي خط أبدًا. وجهة الاتصال التي انضمت ثم غادرت لا تدخل في أي من الأرقام.
المعاملات
audience_idsArray<String>- حتى 50 معرّف جمهور، تُرسل مضمومة بفواصل. اتركه، أو مرّر Array فارغة، للحصول على كل الجماهير. والمعرّف الذي ليس جمهورًا في مساحة العمل هذه يعطي 404 `audience_not_found`، وما يزيد على 50 يعطي 422.
daysInteger- إلى أي مدى تمتد النافذة إلى الوراء، من 1 إلى 1095. وتكون 30 حين لا يُعطى `days:` ولا `minutes:`.
minutesInteger- النافذة بالدقائق، من 1 إلى 1576800، لنافذة أقصر من يوم. وتغلب على `days:` حين يُعطى الاثنان.
grainString- حجم كل فترة فرعية: `day` (الافتراضي) أو `hour` أو `minute`.
offset_minutesInteger- إزاحة المشاهد عن UTC بالدقائق، من -840 إلى 840، كي تبدأ فواصل الأيام والساعات عند حدودها المحلية. والافتراضي 0. و`Time.now.utc_offset / 60` هي إزاحة الجهاز الذي تعمل عليه الشيفرة.
الاستجابة
sinceString- بصيغة ISO 8601 بتوقيت UTC، بداية الفاصل الأول.
untilString- بصيغة ISO 8601 بتوقيت UTC، لحظة القراءة.
totalsHash- يعدّ `contacts` كل شخص مرة واحدة مهما كان عدد القوائم التي هو فيها، ويجمع `memberships` القوائم، فيُعدّ الشخص مرة عن كل قائمة مقروءة تضمه. ويجمع `added` الانضمامات في النافذة، و`lists` عدد الجماهير التي قُرئت، و`busiest` الفاصل الذي شهد أكبر عدد من الانضمامات، أو nil. ويعدّ `subscribed` كل شخص ما زال مشتركًا في واحد على الأقل من الجماهير المقروءة، ويجمع `unsubscribed` إلغاءات الاشتراك داخل النافذة.
seriesArray<Hash>- عنصر واحد لكل جمهور، الأكبر أولًا ثم حسب الاسم: `id` و`name` و`builtin` و`total` أي الأعضاء الآن، و`subscribed` (من ما زالوا مشتركين)، و`before` (من انضموا قبل `since`)، و`added` (من انضموا داخل النافذة)، و`unsubscribed` (من ألغوا اشتراكهم داخلها)، و`buckets` من الأقدم، وكل منها Hash فيه `bucket` و`added` و`unsubscribed`. وهنا تكون قيمة `builtin` هي `true` في الجمهور الافتراضي و`false` في الباقي، لا الـ String الذي يحمله Hash الجمهور. ولا تُسرد إلا الفواصل التي فيها انضمام أو إلغاء اشتراك، بمفاتيح `YYYY-MM-DD` أو `YYYY-MM-DDTHH` أو `YYYY-MM-DDTHH:MM` بالتوقيت المحلي للإزاحة.