بداية سريعة: استخدام مكتبة العميل Bing Custom Search

مقالة
04/27/2022
قراءة خلال 8 دقائق

تحذير

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

ابدأ باستخدام مكتبة عميل Bing Custom Search لـ C#. اتبع هذه الخطوات لتثبيت الحزمة وتجربة التعليمة البرمجية الموفرة كمثال للمهام الأساسية. يُمكّنك The Bing Custom Search API من إنشاء تجارب بحث مخصصة بدون إعلانات للمواضيع التي تهتم بها. يمكن العثور على التعليمة البرمجية المصدر لهذا النموذج على GitHub.

استخدم مكتبة عميل Bing Custom Search لـ C# إلى:

ابحث عن نتائج البحث على الويب، من مثيلBing Custom Search.

الوثائق المرجعية | لحزمة الكود المصدرللمكتبة | نماذج | (NuGet)

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

مثيل Bing Custom Search. انظر التشغيل السريع: أنشئ أول مثيل لـBing Custom Search للحصول على مزيد من المعلومات.
Microsoft .NET Core
أي نسخة من Visual Studio 2017 أو نسخة أحدث
إذا كنت تستخدم Linux/MacOS، يمكن تشغيل هذا التطبيق باستخدام Mono.
حزمة NuGet لـ Bing Custom Search.
- من مستكشف الحلول في Visual Studio، حدد بزر الماوس الأيمن المشروع وحددإدارة حزم NuGet من القائمة. ثبّت حزمة Microsoft.Azure.CognitiveServices.Search.CustomSearch. يؤدي تثبيت حزمة البحث المخصص في NuGet أيضًا إلى تثبيت التجميعات التالية:
  - Microsoft.Rest.ClientRuntime
  - Microsoft.Rest.ClientRuntime.Azure
  - ⁧⁩Newtonsoft.Js⁩

أنشئ مورد Azure

بدء استخدام Bing Custom Search API من خلال إنشاء أحد موارد Azure التالية.

مورد Bing Custom Search

متوفر من خلال بوابة Azure طالما لم تحذف المورد.
استخدم طبقة التسعير المجانية لتجربة الخدمة، وترقيتها لاحقاً إلى مستوى مدفوع للإنتاج.

مورد Multi-Service

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

إنشاء التطبيق وتهيئته

أنشئ تطبيق وحدة تحكم جديد C# في Visual Studio. ثم أضف الحزم التالية إلى مشروعك.
```
using System;
using System.Linq;
using Microsoft.Azure.CognitiveServices.Search.CustomSearch;
```
في الطريقة الرئيسية لتطبيقك، أنشئ مثيل عميل البحث باستخدام مفتاح واجهة برمجة التطبيقات الخاص بك.
```
var client = new CustomSearchAPI(new ApiKeyServiceClientCredentials("YOUR-SUBSCRIPTION-KEY"));
```

إرسال طلب البحث وتلقي رد

أرسل استعلام بحث باستخدام طريقة العميل SearchAsync() واحفظ الرد. تأكد من استبدال YOUR-CUSTOM-CONFIG-ID بمعرِّف تكوين المثيل الخاص بك (يمكنك العثور على المعرِّف في مدخل Bing Custom Search). يبحث هذا المثال عن "Xbox".
```
// This will look up a single query (Xbox).
var webData = client.CustomInstance.SearchAsync(query: "Xbox", customConfig: Int32.Parse("YOUR-CUSTOM-CONFIG-ID")).Result;
```

تُعيد طريقة SearchAsync() كائن WebData. استخدم الكائن لتكرار أي WebPages تم العثور عليه. تعثر هذه التعليمة البرمجية على نتيجة صفحة الويب الأولى وتطبع صفحتي الويب Name وURL.

if (webData?.WebPages?.Value?.Count > 0)
{
    // find the first web page
    var firstWebPagesResult = webData.WebPages.Value.FirstOrDefault();

    if (firstWebPagesResult != null)
    {
        Console.WriteLine("Number of webpage results {0}", webData.WebPages.Value.Count);
        Console.WriteLine("First web page name: {0} ", firstWebPagesResult.Name);
        Console.WriteLine("First web page URL: {0} ", firstWebPagesResult.Url);
    }
    else
    {
        Console.WriteLine("Couldn't find web results!");
    }
}
else
{
    Console.WriteLine("Didn't see any Web data..");
}

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

⁧⁧⁩⁩ إنشاء تطبيق ويب للبحث المخصص⁧⁧⁩⁩

ابدأ باستخدام مكتبة عميل Bing Custom Search لـ Java. اتبع هذه الخطوات لتثبيت الحزمة وتجربة أمثلة التعليمات البرمجية للمهام الأساسية. تُمكِّنك واجهة برمجة تطبيقات Bing Custom Search من إنشاء تجارب بحث مخصصة وخالية من الإعلانات للموضوعات التي تهتم بها. يمكن العثور على التعليمات البرمجية للمصدر لهذا النموذج على ⁧⁩GitHub⁧⁩

استخدم مكتبة عميل Bing Custom Search لـ Java من أجل:

ابحث عن نتائج البحث عبر الويب، من مثيل Bing Custom Search.

⁧⁩ الوثائق المرجعية⁧⁩⁧ | ⁩⁧⁩التعليمات البرمجية لمصدر المكتبة⁧⁩⁧ | ⁩⁧⁩عينات (Maven)⁧⁩⁧ | ⁩⁧⁩مصطنعة⁧⁩

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

اشتراك Azure - ⁧⁩إنشاء حساب مجانًا⁧⁩
الإصدار الحالي من ⁧⁩Java Development Kit(JDK)⁧⁩
⁧⁩أداة إنشاء Gradle⁧⁩ أو مدير تبعية آخر.
مثيل Bing Custom Search. الاطلاع على ⁧⁩التشغيل السريع: أنشئ أول مثيل لـBing Custom Search⁧⁩ للحصول على مزيد من المعلومات.

أنشئ مورد Azure

بدء استخدام Bing Custom Search API من خلال إنشاء أحد موارد Azure التالية.

مورد Bing Custom Search

متوفر من خلال بوابة Azure طالما لم تحذف المورد.
استخدم طبقة التسعير المجانية لتجربة الخدمة، وترقيتها لاحقاً إلى مستوى مدفوع للإنتاج.

مورد Multi-Service

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

بعد الحصول على مفتاح من موردك، ⁧⁩ قم بإنشاء متغير البيئة⁧⁩ للمفتاح المسمى ⁧AZURE_BING_CUSTOM_SEARCH_API_KEY⁩.

إنشاء مشروع Gradle جديد

تلميح

في حالة عدم استخدامك Gradle، يمكنك العثور على مكتبة العميل ومعلومات مديري التبعية الآخرين على ⁧⁩Maven Central Repository⁧⁩.

في إطار نافذة وحدة التحكم (مثل cmd أو PowerShell أو Bash)، يمكنك إنشاء دليل جديد لتطبيقك وانتقل إليه.

mkdir myapp && cd myapp

يمكنك بدء الأمر ⁧gradle init⁩ من دليل العمل. ينتج عن هذا الأمر ملفات إنشاء أساسية لـ Gradle، بما في ذلك ⁧⁩build.gradle.kts⁧⁩ الذي يُستخدم في وقت التشغيل لإنشاء تطبيقك وتكوينه.

gradle init --type basic

عند مطالبتك باختيار ⁧⁩DSL⁧⁩، حدد ⁧⁩Kotlin⁧⁩.

تثبيت مكتبة العميل

حدد build.gradle.kts وافتحه باستخدام IDE أو محرر النص المفضل لديك. ثم النسخ في تكوين البنية هذا. تأكد من إدخال مكتبة العميل ضمن ⁧dependencies⁩ :

plugins {
    java
    application
}
application {
    mainClassName = "main.java.BingCustomSearchSample"
}
repositories {
    mavenCentral()
}
dependencies {
    compile("org.slf4j:slf4j-simple:1.7.25")
    compile("com.microsoft.azure.cognitiveservices:azure-cognitiveservices-customsearch:1.0.2")
}

إنشاء مجلد لعينة التطبيق. من خلال دليل العمل، قم بتنفيذ الأمر التالي:

mkdir src/main/java

انتقل إلى المجلد الجديد، وأنشئ ملفًا يسمى ⁧⁩BingVisualSearchSample.java⁧⁩. افتح الملف، ثم أضف ⁧import⁩ العبارات الآتية:

package main.java;

import com.microsoft.azure.cognitiveservices.search.customsearch.BingCustomSearchAPI;
import com.microsoft.azure.cognitiveservices.search.customsearch.BingCustomSearchManager;
import com.microsoft.azure.cognitiveservices.search.customsearch.models.SearchResponse;
import com.microsoft.azure.cognitiveservices.search.customsearch.models.WebPage;

إنشاء فئة باسم ⁧BingCustomSearchSample⁩

public class BingCustomSearchSample {
}

في الفئة، قم بإنشاء ⁧main⁩ أسلوب ومتغير لمفتاح المورد الخاص بك. إذا قمت بإنشاء متغير البيئة بعد تشغيل التطبيق، فقم بإغلاق المحرر أو IDE أو shell وإعادة فتحه وتشغيله للوصول إلى المتغير. ستقوم بتعريف الأساليب لاحقًا.

public static void main(String[] args) {
    try {

        // Set the BING_CUSTOM_SEARCH_SUBSCRIPTION_KEY and AZURE_BING_SAMPLES_CUSTOM_CONFIG_ID environment variables, 
        // then reopen your command prompt or IDE. If not, you may get an API key not found exception.
        final String subscriptionKey = System.getenv("BING_CUSTOM_SEARCH_SUBSCRIPTION_KEY");
        // If you do not have a customConfigId, you can also use 1 as your value when setting your environment variable.
        final String customConfigId = System.getenv("AZURE_BING_SAMPLES_CUSTOM_CONFIG_ID");

        BingCustomSearchAPI client = BingCustomSearchManager.authenticate(subscriptionKey);

        runSample(client, customConfigId);
    } catch (Exception e) {
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
}

طراز الكائن

عميل Bing Custom Search هو كائن ⁧⁩BingCustomSearchAPI⁧⁩ الذي تم إنشاؤه من⁧⁩BingCustomSearchManager⁧⁩أسلوب⁧⁩ مصادقة()⁧⁩ كائن. يمكنك إرسال طلب بحث باستخدام أسلوب ⁧⁩BingCustomInstances.search()⁧⁩ الخاص بالعميل.

استجابة واجهة برمجة التطبيقات هي كائن ⁧⁩SearchResponse⁧⁩ يتضمن معلومات حول استعلام البحث ونتائجه.

أمثلة التعليمات البرمجية

توضح لك هذه المقتطفات البرمجية كيفية تنفيذ المهام التالية باستخدام مكتبة عميل Bing Custom Search لـ Java:

⁧⁩مصادقة العميل⁧⁩
⁧⁩الحصول على نتائج البحث من مثيل البحث المخصص⁧⁩

مصادقة العميل

يجب أن تتضمن الطريقة الرئيسة كائن ⁧⁩BingCustomSearchManager⁧⁩ الذي يحتفظ بمفتاحك⁧authenticate()⁩ .

BingCustomSearchAPI client = BingCustomSearchManager.authenticate(subscriptionKey);

الحصول على نتائج البحث من مثيل البحث المخصص

استخدم دالة ⁧⁩BingCustomInstances.search()⁧⁩ العميل لإرسال استعلام بحث إلى المثيل المخصص الخاص بك. تحديد⁧withCustomConfig⁩ لمعرف التكوين المخصص، أو الافتراضي إلى ⁧1⁩ . بعد الحصول على استجابة من واجهة برمجة التطبيقات، تحقق ما إذا تم العثور على أي نتائج بحث. إذا كان الأمر كذلك، فاحصل على نتيجة البحث الأولى عن طريق استدعاء ⁧webPages().value().get()⁩ دالة الاستجابة وطباعة اسم النتيجة وعنوان URL.

public static boolean runSample(BingCustomSearchAPI client, String customConfigId) {
    try {

        // This will search for "Xbox" using Bing Custom Search 
        //and print out name and url for the first web page in the results list

        System.out.println("Searching for Query: \"Xbox\"");
        SearchResponse webData = client.bingCustomInstances().search()
            .withCustomConfig(customConfigId != null ? Long.valueOf(customConfigId) : 0)
            .withQuery("Xbox")
            .withMarket("en-us")
            .execute();

        if (webData != null && webData.webPages() != null && webData.webPages().value().size() > 0)
        {
            // find the first web page
            WebPage firstWebPagesResult = webData.webPages().value().get(0);

            if (firstWebPagesResult != null) {
                System.out.println(String.format("Webpage Results#%d", webData.webPages().value().size()));
                System.out.println(String.format("First web page name: %s ", firstWebPagesResult.name()));
                System.out.println(String.format("First web page URL: %s ", firstWebPagesResult.url()));
            } else {
                System.out.println("Couldn't find web results!");
            }
        } else {
            System.out.println("Didn't see any Web data..");
        }

        return true;
    } catch (Exception f) {
        System.out.println(f.getMessage());
        f.printStackTrace();
    }
    return false;
}

شغّل التطبيق

إنشاء التطبيق مع الأمر التالي من الدليل الرئيس لمشروعك:

gradle build

تشغيل التطبيق ⁧run⁩ بهدف:

gradle run

تنظيف الموارد

إذا كنت تريد تنظيف وإلغاء اشتراك الخدمات المعرفية، يمكنك حذف المورد أو مجموعة الموارد. يؤدي حذف مجموعة الموارد إلى حذف أية موارد أخرى مقترنة بها أيضًا.

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

⁧⁧⁩⁩ إنشاء تطبيق ويب للبحث المخصص⁧⁧⁩⁩

ابدأ باستخدام مكتبة العميل Bing Custom Search الخاصة بلغة Python. اتبع هذه الخطوات لتثبيت الحزمة وتجربة نموذج تعليمات البرمجة للمهام الأساسية. يمكنك Bing Custom Search API من إنشاء تجارب بحث مخصصة وخالية من الإعلانات للمواضيع التي تهتم بها. يمكن الاطلاع على التعليمات البرمجية لهذا النموذج GitHub.

استخدم مكتبة العميل Bing Custom Search client على Python من أجل:

البحث عن نتائج البحث على الويب، من مثيل البحث المخصص Bing.

الوثائق المرجعية | لكود مصدر المكتبة | لنماذج | Package (PyPi)

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

مثيل Bing Custom Search. راجع البداية السريعة: إنشاء أول مثيل Bing Custom Search للحصول على مزيد من المعلومات.
Python 2.x أو 3.x
Bing Custom Search SDK لـ Python

أنشئ مورد Azure

بدء استخدام Bing Custom Search API من خلال إنشاء أحد موارد Azure التالية.

مورد Bing Custom Search

متوفر من خلال بوابة Azure طالما لم تحذف المورد.
استخدم طبقة التسعير المجانية لتجربة الخدمة، وترقيتها لاحقاً إلى مستوى مدفوع للإنتاج.

مورد Multi-Service

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

تثبيت مكتبة العميل على Python

تثبيت مكتبة العميل "البحث المخصص" Bing بالأمر التالي.

python -m pip install azure-cognitiveservices-search-customsearch

إنشاء تطبيق جديد

أنشئ ملف Python جديداً في بيئة التطوير المتكاملة المفضلة أو المحرر، وأضف بيانات الاستيراد التالية.

from azure.cognitiveservices.search.customsearch import CustomSearchClient
from msrest.authentication import CognitiveServicesCredentials

إنشاء عميل بحث وتخزين بيانات الاعتماد

إنشاء متغير لمفتاح الاشتراك ونقطة النهاية.
```
subscription_key = 'your-subscription-key'
endpoint = 'your-endpoint'
```
أنشئ مثيل CustomSearchClient باستخدام CognitiveServicesCredentials عنصر مع مفتاح الاشتراك.
```
client = CustomSearchClient(endpoint=endpoint, credentials=CognitiveServicesCredentials(subscription_key))
```
إرسال طلب بحث باستخدام client.custom_instance.search(). إلحاق مصطلح البحث query بالمعلمة، custom_config وتعيينه إلى "معرف التهيئة المخصص" لاستخدام مثيل البحث. يمكنك الحصول على معرفك من مدخل البحث المخصص على Bing، وذلك بالنقر فوق علامة التبويب الإنتاج.
```
web_data = client.custom_instance.search(query="xbox", custom_config="your-configuration-id")
```

إظهار نتائج البحث

عند العثور على أي نتائج بحث في صفحة الويب، احصل على أول صفحة واطبع اسمها وعنوان URL وإجمالي صفحات الويب التي تم العثور عليها.

if web_data.web_pages.value:
    first_web_result = web_data.web_pages.value[0]
    print("Web Pages result count: {}".format(len(web_data.web_pages.value)))
    print("First Web Page name: {}".format(first_web_result.name))
    print("First Web Page url: {}".format(first_web_result.url))
else:
    print("Didn't see any web data..")

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

⁧⁧⁩⁩ إنشاء تطبيق ويب للبحث المخصص⁧⁧⁩⁩

بداية سريعة: استخدام مكتبة العميل Bing Custom Search

هل هذه الصفحة مفيدة؟

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

أنشئ مورد Azure

مورد Bing Custom Search

مورد Multi-Service

إنشاء التطبيق وتهيئته

إرسال طلب البحث وتلقي رد

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

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

أنشئ مورد Azure

مورد Bing Custom Search

مورد Multi-Service

إنشاء مشروع Gradle جديد

تثبيت مكتبة العميل

طراز الكائن

أمثلة التعليمات البرمجية

مصادقة العميل

الحصول على نتائج البحث من مثيل البحث المخصص

شغّل التطبيق

تنظيف الموارد

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

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

أنشئ مورد Azure

مورد Bing Custom Search

مورد Multi-Service

تثبيت مكتبة العميل على Python

إنشاء تطبيق جديد

إنشاء عميل بحث وتخزين بيانات الاعتماد

إظهار نتائج البحث

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