عوامل تصفية الأمان لاقتطاع النتائج في Azure الذكاء الاصطناعي Search

  • مقالة

لا يوفر Azure الذكاء الاصطناعي Search أذونات على مستوى المستند ولا يمكنه تغيير نتائج البحث من داخل الفهرس نفسه حسب أذونات المستخدم. كحل بديل، يمكنك إنشاء عامل تصفية يقوم باقتطاع نتائج البحث استنادا إلى سلسلة تحتوي على هوية مجموعة أو مستخدم.

توضح هذه المقالة نمطا لتصفية الأمان يتضمن الخطوات التالية:

  • تجميع المستندات المصدر بالمحتوى المطلوب
  • إنشاء حقل للمعرفات الأساسية
  • دفع المستندات إلى فهرس البحث للفهرسة
  • الاستعلام عن الفهرس باستخدام دالة التصفية search.in

حول نمط عامل تصفية الأمان

على الرغم من أن Azure الذكاء الاصطناعي Search لا يتكامل مع الأنظمة الفرعية للأمان للوصول إلى المحتوى داخل فهرس، فقد وجد العديد من العملاء الذين لديهم متطلبات أمان على مستوى المستند أن عوامل التصفية يمكنها تلبية احتياجاتهم.

في Azure الذكاء الاصطناعي Search، عامل تصفية الأمان هو عامل تصفية OData عادي يتضمن أو يستبعد نتيجة بحث استنادا إلى قيمة مطابقة، باستثناء أنه في عامل تصفية الأمان، المعايير هي سلسلة تتكون من أساس أمان. لا توجد مصادقة أو تخويل من خلال أساس الأمان. الأساسي هو مجرد سلسلة، تستخدم في تعبير عامل تصفية، لتضمين مستند أو استبعاده من نتائج البحث.

هناك عدة طرق لتحقيق تصفية الأمان. إحدى الطرق هي من خلال فصل معقد لتعبيرات المساواة: على سبيل المثال، Id eq 'id1' or Id eq 'id2'، وما إلى ذلك. هذا الأسلوب عرضة للخطأ ويصعب الاحتفاظ بها، وفي الحالات التي تحتوي فيها القائمة على مئات أو آلاف القيم، يبطئ وقت استجابة الاستعلام لعدة ثوان.

الحل الأفضل هو استخدام الدالة search.in لعوامل تصفية الأمان، كما هو موضح في هذه المقالة. إذا كنت تستخدم search.in(Id, 'id1, id2, ...') بدلا من تعبير المساواة، يمكنك توقع أوقات استجابة ثانية فرعية.

المتطلبات الأساسية

  • يجب أن يكون الحقل الذي يحتوي على هوية المجموعة أو المستخدم سلسلة مع السمة القابلة للتصفية. يجب أن تكون مجموعة. لا ينبغي أن يسمح بالقيم الخالية.

  • يجب أن توفر الحقول الأخرى في المستند نفسه المحتوى الذي يمكن لتلك المجموعة أو المستخدم الوصول إليه. في مستندات JSON التالية، تحتوي حقول "security_id" على هويات مستخدمة في عامل تصفية الأمان، وسيتم تضمين الاسم والراتب والحالة الزوجية إذا تطابقت هوية المتصل مع "security_id" المستند.

    {  
    "Employee-1": {  
        "id": "100-1000-10-1-10000-1",
        "name": "Abram",   
        "salary": 75000,   
        "married": true,
        "security_id": "10011"
    },
    "Employee-2": {  
        "id": "200-2000-20-2-20000-2",
        "name": "Adams",   
        "salary": 75000,   
        "married": true,
        "security_id": "20022"
    } 
}

    إشعار

    لا تتناول هذه المقالة عملية استرداد المعرفات الأساسية وإدراج هذه السلاسل في المستندات المصدر التي يمكن فهرستها بواسطة Azure الذكاء الاصطناعي Search. راجع وثائق موفر خدمة الهوية للحصول على المساعدة في الحصول على المعرفات.

إنشاء حقل أمان

في فهرس البحث، ضمن مجموعة الحقول، تحتاج إلى حقل واحد يحتوي على هوية المجموعة أو المستخدم، على غرار حقل "security_id" الوهمي في المثال السابق.

  1. إضافة حقل أمان ك Collection(Edm.String). تأكد من أنه يحتوي على سمة filterable معينة إلى true بحيث تتم تصفية نتائج البحث استنادا إلى الوصول الذي يمتلكه المستخدم. على سبيل المثال، إذا قمت بتعيين group_ids الحقل إلى للمستند الذي file_name يحتوي على ["group_id1, group_id2"] "secured_file_b"، فإن المستخدمين الذين ينتمون إلى معرفات المجموعة "group_id1" أو "group_id2" فقط لديهم حق الوصول للقراءة إلى الملف.

    قم بتعيين سمة الحقل retrievable إلى false بحيث لا يتم إرجاعه كجزء من طلب البحث.

  2. تتطلب الفهارس مفتاح مستند. يستوفي حقل "file_id" هذا المطلب. يجب أن تحتوي الفهارس أيضا على محتوى قابل للبحث. يمثل الحقلان "file_name" و"file_description" ذلك في هذا المثال.

    POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2023-11-01
{
     "name": "securedfiles",  
     "fields": [
         {"name": "file_id", "type": "Edm.String", "key": true, "searchable": false },
         {"name": "file_name", "type": "Edm.String", "searchable": true },
         {"name": "file_description", "type": "Edm.String", "searchable": true },
         {"name": "group_ids", "type": "Collection(Edm.String)", "filterable": true, "retrievable": false }
     ]
 }

دفع البيانات إلى الفهرس باستخدام واجهة برمجة تطبيقات REST

إرسال طلب HTTP POST إلى مجموعة المستندات لنقطة نهاية عنوان URL للفهرس (راجع المستندات - الفهرس). نص طلب HTTP هو عرض JSON للمستندات المراد فهرستها:

POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2023-11-01

في نص الطلب، حدد محتوى مستنداتك:

{
    "value": [
        {
            "@search.action": "upload",
            "file_id": "1",
            "file_name": "secured_file_a",
            "file_description": "File access is restricted to the Human Resources.",
            "group_ids": ["group_id1"]
        },
        {
            "@search.action": "upload",
            "file_id": "2",
            "file_name": "secured_file_b",
            "file_description": "File access is restricted to Human Resources and Recruiting.",
            "group_ids": ["group_id1", "group_id2"]
        },
        {
            "@search.action": "upload",
            "file_id": "3",
            "file_name": "secured_file_c",
            "file_description": "File access is restricted to Operations and Logistics.",
            "group_ids": ["group_id5", "group_id6"]
        }
    ]
}

إذا كنت بحاجة إلى تحديث مستند موجود بقائمة المجموعات، يمكنك استخدام merge الإجراء أو mergeOrUpload :

{
    "value": [
        {
            "@search.action": "mergeOrUpload",
            "file_id": "3",
            "group_ids": ["group_id7", "group_id8", "group_id9"]
        }
    ]
}

تطبيق عامل تصفية الأمان في الاستعلام

لاقتطاع المستندات استنادا إلى group_ids الوصول، يجب إصدار استعلام بحث باستخدام عامل group_ids/any(g:search.in(g, 'group_id1, group_id2,...')) تصفية، حيث "group_id1، group_id2,..." هي المجموعات التي ينتمي إليها مصدر طلب البحث.

يتطابق عامل التصفية هذا مع كافة المستندات التي group_ids يحتوي الحقل على أحد المعرفات المحددة لها. للحصول على تفاصيل كاملة حول البحث في المستندات باستخدام Azure الذكاء الاصطناعي Search، يمكنك قراءة البحث في المستندات.

يوضح هذا النموذج كيفية إعداد الاستعلام باستخدام طلب POST.

إصدار طلب HTTP POST:

POST https://[service name].search.windows.net/indexes/securedfiles/docs/search?api-version=2020-06-30
Content-Type: application/json  
api-key: [admin or query key]

حدد عامل التصفية في نص الطلب:

{
   "filter":"group_ids/any(g:search.in(g, 'group_id1, group_id2'))"  
}

يجب أن تحصل على المستندات مرة أخرى حيث group_ids تحتوي إما على "group_id1" أو "group_id2". بمعنى آخر، يمكنك الحصول على المستندات التي يمكن لمصدر الطلب الوصول إليها للقراءة.

{
 [
   {
    "@search.score":1.0,
     "file_id":"1",
     "file_name":"secured_file_a",
   },
   {
     "@search.score":1.0,
     "file_id":"2",
     "file_name":"secured_file_b"
   }
 ]
}

الخطوات التالية

توضح هذه المقالة نمطا لتصفية النتائج استنادا إلى هوية المستخدم والدالة search.in() . يمكنك استخدام هذه الدالة لتمرير المعرفات الأساسية للمستخدم الطالب لمطابقتها مع المعرفات الأساسية المقترنة بكل مستند هدف. عند معالجة طلب بحث، تقوم الدالة search.in بتصفية نتائج البحث التي لا يملك أي من أساسيات المستخدم حق الوصول للقراءة لها. يمكن أن تمثل المعرفات الأساسية أشياء مثل مجموعات الأمان أو الأدوار أو حتى هوية المستخدم الخاصة.

للحصول على نمط بديل يستند إلى معرف Microsoft Entra، أو لإعادة النظر في ميزات الأمان الأخرى، راجع الارتباطات التالية.