البحث عن الكيانات من خلال استخدام Bing Entity API

تحذير

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

اقتراح مصطلحات البحث باستخدام Bing Autosuggest API

إذا قمت بتوفير مربع بحث حيث يدخل المستخدم مصطلح البحث الخاص به، استخدم واجهة برمجة تطبيقات Bing Autosuggest لتحسين التجربة. تقوم واجهة برمجة التطبيقات بإرجاع سلاسل الاستعلام المقترحة بناءً على مصطلحات البحث الجزئي مثل أنواع المستخدمين.

بعد إدخال المستخدم لمصطلح البحث الخاص به، يقوم عنوان URL بترميز المصطلح قبل تعيين معلمة الاستعلام q. على سبيل المثال، إذا قام المستخدم بإدخال Marcus Appel، فقم بتعيين q إلى Marcus+Appel أو Marcus%20Appel.

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

"queryContext": {
    "originalQuery": "hollo wrld",
    "alteredQuery": "hello world",
    "alterationOverrideQuery": "+hollo wrld",
    "adultIntent": false
}

استجابة Bing Entity Search API

تحتوي استجابة واجهة برمجة التطبيقات على عنصر SearchResponse. إذا عثر Bing على كيان أو مكان ذي صلة أو عنصر يشمل الحقل entitiesأو places أو كليهما. وبخلاف ذلك، لا يشمل عنصر الاستجابة أيًا من الحقلين.

ملاحظة

تدعم استجابات الكيانات أسواقًا متعددة، لكن استجابة الأماكن تدعم فقط مواقع الأنشطة التجارية الأمريكية.

الحقل entities هو عنصر EntityAnswer يحتوي على قائمة عناصر الكيان (انظر الحقلvalue). من الممكن أن تحتوي القائمة على كيان واحد مهيمن أو كيانات متعددة لإزالة الغموض أو كليهما.

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

تشمل الكيانات شخصيات معروفة مثل المطربين والممثلين والرياضيين والعارضين وما إلى ذلك؛ والأماكن والمعالم مثل Mount Rainier أو Lincoln Memorial؛ وأشياء مثل عنوان الموز أو العنوان الذهبي أو الكتاب أو الفيلم. يحتوي الحقل entityPresentationInfo على تلميحات تحدد نوع الكيان. على سبيل المثال، إذا كان شخصًا أو فيلمًا أو حيوانًا أو جاذبية. للحصول على قائمة بالأنواع المحتملة، انظر أنواع الكيانات

"entityPresentationInfo": {
    "entityScenario": "DominantEntity",
    "entityTypeHints": ["Attraction"],
    "entityTypeDisplayHint": "Mountain"
}, ...

يُظهر ما يلي استجابة تتضمن كيانًا مهيمنًا وكيانًا مزيلاً للغموض.

{
    "_type": "SearchResponse",
    "queryContext": {
        "originalQuery": "Mount Rainier"
    },
    "entities": {
        "value": [{
            "contractualRules": [{
                "_type": "ContractualRules/LicenseAttribution",
                "targetPropertyName": "description",
                "mustBeCloseToContent": true,
                "license": {
                    "name": "CC-BY-SA",
                    "url": "https://creativecommons.org/licenses/by-sa/3.0/"
                },
                "licenseNotice": "Text under CC-BY-SA license"
            },
            {
                "_type": "ContractualRules/LinkAttribution",
                "targetPropertyName": "description",
                "mustBeCloseToContent": true,
                "text": "contoso.com",
                "url": "http://contoso.com/mount_rainier"
            },
            {
                "_type": "ContractualRules/MediaAttribution",
                "targetPropertyName": "image",
                "mustBeCloseToContent": true,
                "url": "http://contoso.com/mount-rainier"
            }],
            "webSearchUrl": "https://www.bing.com/search?q=Mount%20Rainier...",
            "name": "Mount Rainier",
            "url": "http://www.northwindtraders.com/",
            "image": {
                "name": "Mount Rainier",
                "thumbnailUrl": "https://www.bing.com/th?id=A4ae343983daa4...",
                "provider": [{
                    "_type": "Organization",
                    "url": "http://contoso.com/mount_rainier"
                }],
                "hostPageUrl": "http://contoso.com/commons/7/72/mount_rain...",
                "width": 110,
                "height": 110
            },
            "description": "Mount Rainier is 14,411 ft tall and the highest mountain...",
            "entityPresentationInfo": {
                "entityScenario": "DominantEntity",
                "entityTypeHints": ["Attraction"]
            },
            "bingId": "38b9431e-cf91-93be-0584-c42a3ecbfdc7"
        },
        {
            "contractualRules": [{
                "_type": "ContractualRules/MediaAttribution",
                "targetPropertyName": "image",
                "mustBeCloseToContent": true,
                "url": "http://contoso.com/mount_rainier_national_park"
            }],
            "webSearchUrl": "https://www.bing.com/search?q=Mount%20Rainier%20National...",
            "name": "Mount Rainier National Park",
            "url": "http://worldwideimporters.com/",
            "image": {
                "name": "Mount Rainier National Park",
                "thumbnailUrl": "https://www.bing.com/th?id=A91bdc5a1b648a695a39...",
                "provider": [{
                    "_type": "Organization",
                    "url": "http://contoso.com/mount_rainier_national_park"
                }],
                "hostPageUrl": "http://contoso.com/en/7/7a...",
                "width": 50,
                "height": 50
            },
            "description": "Mount Rainier National Park is a United States National Park...",
            "entityPresentationInfo": {
                "entityScenario": "DisambiguationItem",
                "entityTypeHints": ["Organization"]
            },
            "bingId": "29d4b681-227a-3924-7bb1-8a54e8666b8c"
        }]
    }
}

يشمل الكيان حقل name وdescription وimage. عند عرض هذه الحقول في تجربة المستخدم الخاصة بك، فيجب أن تنسبها. يحتوي الحقل contractualRules على قائمة بالإسنادات التي يجب تطبيقها. تحدد القاعدة التعاقدية للحقل الذي ينطبق عليه الإسناد. للحصول على معلومات بشأن تطبيق الإسناد، انظر الإسناد.

"contractualRules": [{
    "_type": "ContractualRules/LicenseAttribution",
    "targetPropertyName": "description",
    "mustBeCloseToContent": true,
    "license": {
        "name": "CC-BY-SA",
        "url": "https://creativecommons.org/licenses/by-sa/3.0/"
    },
    "licenseNotice": "Text under CC-BY-SA license"
},
{
    "_type": "ContractualRules/LinkAttribution",
    "targetPropertyName": "description",
    "mustBeCloseToContent": true,
    "text": "contoso.com",
    "url": "http://contoso.com/wiki/Mount_Rainier"
},
{
    "_type": "ContractualRules/MediaAttribution",
    "targetPropertyName": "image",
    "mustBeCloseToContent": true,
    "url": "http://contoso.com/wiki/Mount_Rainier"
}], ...

عند عرض معلومات الكيان (الاسم والوصف والصورة)، يجب أيضًا استخدام عنوان URL في الحقل webSearchUrl للارتباط بصفحة نتائج بحث Bing المحتوية على الكيان.

البحث عن أماكن

الحقل places هو عنصر LocalEntityAnswer يحتوي على قائمة عناصر المكان (انظر أنواع الكيانات لمزيد من المعلومات). تحتوي القائمة على كيان محلي واحد أو أكثر يقوم بتلبية الطلب.

تشمل الأماكن مطعمًا أو فنادق أو أنشطة تجارية محلية. يحتوي الحقل entityPresentationInfo على تلميحات تقوم بتحديد نوع الكيان المحلي. تحتوي القائمة على قائمة تلميحات مثل Place وLocalBusiness وRestaurant. كل تلميح متتالي في الصفيف يضيق نوع الكيان. للحصول على قائمة بالأنواع المحتملة، انظر أنواع الكيانات

"entityPresentationInfo": {
    "entityScenario": "ListItem",
    "entityTypeHints": ["Place",
    "LocalBusiness",
    "Restaurant"]
}, ...

ملاحظة

تدعم استجابات الكيانات أسواقًا متعددة، لكن استجابة الأماكن تدعم فقط مواقع الأنشطة التجارية الأمريكية.

تتطلب الاستعلامات المحلية المدركة للكيان مثل المطعم القريب مني موقع المستخدم لتقديم نتائج دقيقة. يجب أن تستخدم طلباتك دائمًا رؤوس X-Search-Location وX-MSEdge-ClientIP لتحديد موقع المستخدم. إذا كان Bing يعتقد أن الاستعلام يستفيد من موقع المستخدم، فإنه يعين الحقل askUserForLocationلـ QueryContext إلى true.

{
    "_type": "SearchResponse",
    "queryContext": {
        "originalQuery": "Sinful Bakery and Cafe",
        "askUserForLocation": true
    },
    ...
}

تشمل نتيجة المكان اسم المكان وعنوانه ورقم هاتفه وعنوان URL لموقع الكيان على الويب. عند عرض معلومات الكيان، يجب أيضًا استخدام عنوان URL في الحقل webSearchUrl للارتباط بصفحة نتائج بحث Bing المحتوية على الكيان.

"places": {
    "value": [{
        "_type": "Restaurant",
        "webSearchUrl": "https://www.bing.com/search?q=Sinful%20Bakery...",
        "name": "Liberty's Delightful Sinful Bakery & Cafe",
        "url": "http://libertysdelightfulsinfulbakeryandcafe.com/",
        "entityPresentationInfo": {
            "entityScenario": "ListItem",
            "entityTypeHints": ["Place",
            "LocalBusiness",
            "Restaurant"]
        },
        "address": {
            "addressLocality": "Seattle",
            "addressRegion": "WA",
            "postalCode": "98112",
            "addressCountry": "US",
            "neighborhood": "Madison Park"
        },
        "telephone": "(800) 555-1212"
    }]
}

ملاحظة

لا يجوز لك أو لطرف ثالث نيابة عنك استخدام أو الاحتفاظ أو تخزين موقتًا أو تخزين أو مشاركة أو توزيع أي بيانات من Entities API لغرض اختبار أو تطوير أو تدريب أو توزيع أو إتاحة أي خدمة أو خاصية غير تابعة لـ Microsoft.

إسناد البيانات

تحتوي استجابات Bing Entity API على معلومات مملوكة لأطراف ثالثة. أنت مسؤول عن التأكد من أن استخدامك مناسب، على سبيل المثال من خلال الامتثال لأي ترخيص مشاع إبداعي قد تعتمد عليه تجربة المستخدم الخاصة بك.

إذا كانت الإجابة أو النتيجة تشمل الحقول contractualRules أو attributions أو provider، يجب عليك إسناد البيانات. إذا لم تشمل الإجابة أيًا من هذه الحقول، فلا يلزم الإسناد. إذا كانت الإجابة تشمل الحقل contractualRulesوالحقلين attributions وprovider أو أيًا منهما، يجب عليك استخدام القواعد التعاقدية لإسناد البيانات.

يوضح المثال التالي كيانًا يشمل قاعدة تعاقدية MediaAttribution وصورة تشمل الحقل provider. تعرف قاعدة MediaAttribution الصورة على أنها هدف للقاعدة، لذلك يمكنك تجاهل حقل الصورة providerواستخدام قاعدة MediaAttribution بدلاً من ذلك لتوفير الإسناد.

"value": [{
    "contractualRules": [
        ...
        {
            "_type": "ContractualRules/MediaAttribution",
            "targetPropertyName": "image",
            "mustBeCloseToContent": true,
            "url": "http://contoso.com/mount_rainier"
        }
    ],
    ...
    "image": {
        "name": "Mount Rainier",
        "thumbnailUrl": "https://www.bing.com/th?id=A46378861201...",
        "provider": [{
            "_type": "Organization",
            "url": "http://contoso.com/mount_rainier"
        }],
        "hostPageUrl": "http://www.graphicdesigninstitute.com/Uploaded...",
        "width": 110,
        "height": 110
    },
    ...
}]

إذا كانت القاعدة التعاقدية تشمل الحقل targetPropertyName، فإن القاعدة تنطبق فقط على الحقل المستهدف. وإلا، تنطبق القاعدة على العنصر الأصلي الذي يحتوي على الحقل contractualRules.

في المثال التالي، تشمل القاعدة LinkAttribution الحقل targetPropertyName، لذلك تنطبق القاعدة على الحقل description. بالنسبة للقواعد التي تنطبق على حقول معينة، يجب عليك تضمين سطر يتبع البيانات المستهدفة مباشرةً التي تحتوي على ارتباط تشعبي إلى موقع الويب الخاص بالموفر. على سبيل المثال، لإسناد الوصف، قم بإدراج سطر مباشرةً بعد نص الوصف الذي يحتوي على ارتباط تشعبي إلى البيانات الموجودة على موقع الويب الخاص بالموفر، وفي هذه الحالة قم بإنشاء ارتباط إلى contoso.com.

"entities": {
    "value": [{
            ...
            "description": "Marcus Appel is a former American....",
            ...
            "contractualRules": [{
                    "_type": "ContractualRules/LinkAttribution",
                    "targetPropertyName": "description",
                    "mustBeCloseToContent": true,
                    "text": "contoso.com",
                    "url": "http://contoso.com/cr?IG=B8AD73..."
                 },
            ...
  

إسناد الترخيص

إذا كانت قائمة القواعد التعاقدية تشمل قاعدة LicenseAttribution، يجب عليك عرض الإشعار على السطر فورًا بعد المحتوى الذي ينطبق عليه الترخيص. تستخدم القاعدة LicenseAttribution الحقل targetPropertyName لتعريف الخاصية التي ينطبق عليها الترخيص.

يوضح ما يلي مثالاً يشمل القاعدة LicenseAttribution.

يجب أن يشمل إشعار الترخيص الذي تعرضه ارتباطًا تشعبيًا إلى موقع الويب الذي يحتوي على معلومات بشأن الترخيص. عادةً ما تجعل اسم الترخيص ارتباطًا تشعبيًا. على سبيل المثال، إذا كان الإشعار هو نص ضمن ترخيص CC-BY-SA وكان CC-BY-SA هو اسم الترخيص، يمكنك جعل CC-BY-SA ارتباطًا تشعبيًا.

إسناد الارتباط التشعبي والنص

عادة ما تُستخدم قواعد LinkAttribution وTextAttribution لتحديد موفر البيانات. يقوم الحقل targetPropertyName بتعريف الحقل الذي تنطبق عليه القاعدة.

لإسناد الموفرين، قم بإدراج سطر بعد المحتوى الذي تنطبق عليه عمليات الإسناد مباشرة (على سبيل المثال، الحقل المستهدف). يجب تمييز السطر بوضوح للإشارة إلى أن مقدمي الخدمات هم مصدر البيانات. على سبيل المثال، «بيانات من: contoso.com». فيما يتعلق بالقواعد LinkAttribution، يجب إنشاء ارتباط تشعبي إلى موقع ويب الموفر.

يوضح ما يلي مثالاً يشمل القواعد LinkAttribution وTextAttribution.

إسناد الوسائط

إذا كان الكيان يشمل صورة وقمت بعرضها، يجب عليك توفير رابط النقر إلى موقع الويب الخاص بالموفر. إذا كان الكيان يشمل قاعدة MediaAttribution، فاستخدم عنوان URL للقاعدة لإنشاء ارتباط النقر. وإلا، استخدم عنوان URL المضمن في حقل الصورة provider من أجل إنشاء ارتباط النقر.

يوضح ما يلي مثالاً يشمل حقل الصورة provider والقواعد التعاقدية. نظرًا إلى أن المثال يشمل القاعدة التعاقدية، فإنه يمكنك تجاهل حقل الصورة provider وتطبيق القاعدة MediaAttribution.

البحث أو تجربة شبه البحث

تمامًا كما هو الحال في Bing Web Search API، لا يجوز استخدام Bing Entity Search API إلا كنتيجة لاستعلام أو بحث مباشر من المستخدم، أو كنتيجة لإجراء داخل تطبيق أو تجربة يمكن تفسيرها منطقيًا على أنها طلب بحث للمستخدم. فيما يلي بعض الأمثلة لأغراض التوضيح على البحث المقبول أو التجارب الشبيهة بالبحث.

• يقوم المستخدم بإدخال استعلام مباشرة في مربع البحث في التطبيق
• يختار المستخدم نصًا أو صورة معينة ويطلب «مزيد من المعلومات» أو «معلومات إضافية»
• يسأل المستخدم روبوت البحث عن موضوع معين
• يكمن المستخدم في عنصر أو كيان معين في سيناريو نوع البحث المرئي

إذا لم تكن متأكدًا مما إذا كان يمكن اعتبار تجربتك تجربة شبيهة بالبحث، فمن المستحسن أن تتحقق مع Microsoft.

طلبات التقييد

تحدد الخدمة ونوع اشتراكك عدد الاستعلامات في الثانية (QPS) التي يمكنك إجراؤها. تأكد من أن تطبيقك يتضمن منطق البقاء ضمن حصتك. إذا تم استيفاء حد QPS أو تجاوزه، يفشل الطلب ويتم إرجاع تعليمة برمجية حالة HTTP 429. تتضمن الاستجابة العنوان Retry-After، الذي يشير إلى المدة التي يجب أن تنتظرها قبل إرسال طلب آخر.

رفض الخدمة مقابل التقييد

تميز الخدمة بين هجوم لقطع الخدمة (DoS) وانتهاك QPS. إذا اشتبهت الخدمة في هجوم DoS، ينجح الطلب (تعليمة برمجية حالة HTTP هو 200 OK). ومع ذلك، فإن نص الاستجابة فارغ.

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

• جرب التشغيل السريع لبدء البحث عن الكيانات باستخدام Bing Entity Search API.