إدراج بنية الفلتر واستخدامه

يصف هذا الدليل بنية فلتر القوائم وكيفية فلترة مختلف والموارد.

يمكن لبعض طرق واجهة برمجة التطبيقات قبول فلتر لتقييد الموارد التي يتم عرضها في الاستجابة.

ملخّص

يوفّر هذا القسم نظرة عامة سريعة على بنية بنية فلاتر القوائم.

• الفلتر هو سلسلة تحتوي على expression. expression هي قيمة منطقية مزيج من المقارنات:

  expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }
  expression = ( expression )
  

• يتطابق comparison مع حقل مورد بقيمة. يمكنك استخدام جميع عوامل المقارنة الشائعة.

  comparison = name OP value
  OP = "<=" | "<" | ">=" | ">"  | "!=" | "=" | ":"
  

  يمكن استخدام عامل has، وهو نقطتان (:)، على السلاسل الحقول. راجِع القسم تحتوي على عامل تشغيل لمعرفة التفاصيل.

• يمكنك استخدام الأنواع التالية من القيم في الفلاتر:

  • Numbers
  • السلاسل
  • التعبيرات الموضوعة بين قوسين

  value = number| string | "*" | "(" expression ")"
  

• يمكن أن تمثل السلاسل ما يلي:

  • نص عشوائي
  • قيم منطقية
  • قيم التعداد
  • الطوابع الزمنية

التعبيرات المنطقية

expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}

تتم العمليات بالترتيب التالي:

1. NOT
2. OR
3. AND

على سبيل المثال، التعبيرات التالية متساوية:

a OR NOT b AND NOT c OR d

(a OR (NOT b)) AND ((NOT c) OR d)

يمكنك حذف عامل التشغيل AND بين المقارنات. على سبيل المثال، ما يلي الفلاتر هي نفسها:

c=d AND e=f

c=d e=f

يمكنك استخدام الواصلة (-) كبديل لـ NOT. لا يمكن أن يكون هناك المسافة بين الواصلة (-) والمقارنة التالية. على سبيل المثال، الفلاتر التالية هي نفسها:

NOT e=f

-e=f

المقارنات

يوضِّح هذا القسم مقارنات "name OP value" على النحو التالي:

comparison = name OP value

أين

OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"

الجانب الأيسر من المقارنة هو اسم مسار حقل مورد واجهة برمجة التطبيقات. ويتألف الاسم من سلسلة من معرّفات الموارد المرتبطة بالنقطة (.). يكون كل معرِّف حقل متبوعًا بالمستوى التالي من الأسماء لهذا الحقل. بالنسبة على سبيل المثال، لنفترض أن موردًا يحتوي على حقل معقد item يتضمن حقلاً آخر الحقل المعقد tool، الذي يحتوي على حقل باسم shape. في فلتر لهذا يمكنك الرجوع إلى شكل باسم item.tool.shape.

ويكون الجانب الأيمن عادةً عبارة عن قيمة عددية يتم تحويلها إلى قيمة الكتابة ومقارنته بها. اطّلِع على أنواع القيمة الحرفية. لمزيد من التفاصيل.

يمكن أيضًا التعبير عن الجانب الأيمن من المقارنة على أنه قيمة منطقية بين قوسين مزيج من القيم الحرفية و/أو التعبيرات المنطقية التي تحتوي على القيم الحرفية (التي تسبقها NOT أو بدونها). اسم الجانب الأيسر تطبيق عامل المقارنة على كل قيمة من القيم. على سبيل المثال، الفلاتر التالية هي نفسها:

deal.name = ("test 1" OR "test 2")

deal.name = "test 1" OR deal.name = "test 2"

إليك مثال آخر أكثر تعقيدًا للاثنين المكافئين الفلاتر:

deal.name = ("test 1" OR "test 2" AND (NOT "test3" OR "test4"))

(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = "test3") OR deal.name = "test4")

الأنواع الحرفية للقيمة

يمكن تصنيف قيمة الجانب الأيمن لعامل المقارنة إلى عدد سلسلة القيم الحرفية.

العدد

يصف هذا القسم تمثيل القيم الحرفية الرقمية.

سلسلة

يصف هذا القسم الأنواع التي يمكنك كتابتها كسلسلة حرفية في بناء جملة التصفية.

عوامل تشغيل المقارنة

في ما يلي عوامل تشغيل المقارنة:

• أقل من أو يساوي: "<="
• أقل من: "<"
• أكبر من أو يساوي: ">="
• أكبر من: ">"
• لا يساوي: "!="
• يساوي: "="
• يحتوي على: ":"

تنطبق عوامل التشغيل هذه على القيمة المزدوجة والصحيحة والمنطقية والقيم التعداد والطابع الزمني الأنواع.

تتضمّن عامل تشغيل.

يمكنك استخدام عامل التشغيل HAS (:) لإجراء عمليات خاصة على ما يلي: الحقول:

السلاسل الفرعية

عند استخدام عامل التشغيل HAS لمقارنة القيم في عمود سلسلة نصية، سيعمل العامل كعملية سلسلة فرعية. على سبيل المثال: تعرض الدالة name:"abcd" جميع الحالات التي يكون فيها name سلسلة تحتوي على "abcd"

التحقُّق من تواجد الأفراد في المنزل

عند استخدام عامل التشغيل HAS مع الرمز الخاص *، يتحقق عامل التشغيل HAS من عدم وجود قيم غير فارغة. على سبيل المثال: تعرض الدالة name:* جميع الحالات التي لا تكون فيها السمة name صفرًا أو غير متوفّرة أو غير محدّدة.

عند استخدام عامل التشغيل HAS مع قيم ليست سلسلة، فإنه يتصرف بالطريقة نفسها عامل التشغيل EQUALS (=). على سبيل المثال، يتصرف isCompleted:true في بنفس طريقة isCompleted = true.

الحقول المتكرّرة

يمكنك استخدام عامل التشغيل HAS (:) للفلترة بناءً على مورد متكرّر لواجهة برمجة التطبيقات. الحقل، طالما أن ما يلي صحيح:

1. يتوفّر مكوّن واحد متكرّر على مسار معرّف الحقل.
2. المعرّف الأخير لمسار الحقل هو من نوع عددي

لا يمكن الفلترة في الحقول المتكرّرة المدمجة.

وفي ما يلي مثال لذلك:

تتضمن الدالة item الحقل colors، الذي يحتوي على قيم سلسلة مثل "red". "blue"، و"yellow".

• تُرجع item.colors:("red") جميع العناصر التي تحتوي على القيمة "red" في الحقل "colors".
• تُرجع item.colors:("red" "yellow") جميع السلع التي تحتوي على كلٍ من "red" و "yellow" في الحقل colors.
• يمكن إرجاع جميع السلع التي تتضمّن "red" أو من خلال item.colors:("red" OR "yellow") "yellow" في الحقل colors.

تتضمّن item أيضًا حقل tools متكرّرًا، وهو كائن معقد ذو قيمة عددية. الحقل shape، الذي يمكن أن تكون قيمه "square" أو "round".

• تُرجع item.tools.shape:("square") كل السلع التي تحمل الشكل "square".
• تُرجع item.tools.shape:("square" "round") جميع السلع التي تحتوي على أداة على شكل "square" وأداة على شكل "round".
• item.tools.shape:("square" OR "round") يؤدي إلى إرجاع جميع العناصر التي تحتوي على أداة الشكل "square" أو أداة على شكل "round".

حقول مدمَجة لم تتم تعبئتها

الحقول المتداخلة هي حقول فرعية لحقول على مستوى الجذر، على سبيل المثال shape في item.tools.shape هو حقل مدمج من items.tools.

يتم ضبط الحقول على مستوى الجذر تلقائيًا على "خطأ". تتم تلقائيًا تعبئة الحقول المتداخلة.

لا يتم عرض الكائنات ذات الحقول المتداخلة غير المُعبأة باستخدام القيمة السالبة الفلاتر (!=).

وفي ما يلي مثال لذلك:

تتضمن الدالة item.tools تعدادًا size يمكن ضبط قيمته على "SMALL"، "MEDIUM"، أو "LARGE".

إذا توفّرت لديك العناصر التالية:

{
  "name": "item1",
  "tools": {
    "size": "MEDIUM"
  }
},
{
  "name": "item2",
  "tools": {
    "size": "LARGE"
  }
},
{
  "name": "item3"
}

يتم إرجاع مكالمة إلى items.list باستخدام الفلتر السالب "tools.size != SMALL" ما يلي:

{
  "items": [
    {
      "name": "item1",
      "tools": {
        "size": "MEDIUM"
      }
    },
    {
      "name": "item2",
      "tools": {
        "size": "LARGE"
      }
    }
  ]
}

بما أنّه لم يتم ضبط item.tools.size من أجل item3، لم يتم ضبط الفلتر السلبي. لعرض الكائن item3.

أمثلة