Entitások keresése a Bing Entity API-val

Cikk
02/01/2019

Figyelmeztetés

2020. október 30-án a Bing Search API-k átkerültek az Azure AI-szolgáltatásokból a Bing Search Servicesbe. Ez a dokumentáció csak referenciaként szolgál. A frissített dokumentációt a Bing search API dokumentációjában találja. Az új Azure-erőforrások Bing-kereséshez való létrehozásával kapcsolatos útmutatásért lásd: Bing Search-erőforrás létrehozása a Azure Marketplace keresztül.

Keresési kifejezések ajánlása a Bing Autosuggest API-val

Ha biztosít egy olyan keresőmezőt, ahol a felhasználók megadhatják a keresőkifejezést, a Bing Autosuggest API használatával kényelmesebbé teheti a felhasználói élményt. Az API javasolt lekérdezési sztringeket ad vissza a részleges keresőkifejezések alapján, miközben a felhasználó gépel.

Miután a felhasználó megadja a keresőkifejezést, kódolja URL-címként a karakterláncot a q lekérdezési paraméter beállítása előtt. Ha például a felhasználó a Marcus Appel kifejezésre keres, a q értéke legyen Marcus+Appel vagy Marcus%20Appel.

Ha a keresőkifejezésben elírás van, a keresésre adott válasz tartalmaz egy QueryContext objektumot. Az objektum az eredeti és a javított helyesírást is mutatja, amelyet a Bing a keresés során használt.

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

A Bing Entity Search API válasza

Az API-válasz tartalmaz egy SearchResponse objektumot. Ha a Bing talál egy vonatkozó entitást vagy helyet, az objektum tartalmazza az entities mezőt, a places mezőt, vagy mindkettőt. Ha nem talál, akkor a válaszobjektum egyik mezőt sem tartalmazza.

Megjegyzés

Az entitásválaszok több piacot is támogatnak, de a „helyek” típusú válaszok csak az Egyesült Államokban található vállalkozásokat támogatják.

Az entities mező egy EntityAnswer objektum, amely az Entitás objektumok listáját tartalmazza (lásd: value mező). A lista tartalmazhat egyetlen domináns entitást, több egyértelműsítő entitást, vagy mindkettőt.

A rendszer egy domináns entitást ad vissza, ha a Bing úgy véli, hogy ez az egyetlen entitás, amely megfelel a kérésnek (nincs kétértelműség arról, hogy melyik entitás teljesíti a kérést). Ha több entitás is megfelelhet a kérelemnek, a lista több egyértelműsítő entitást tartalmaz. Ha például a kérelem egy filmes franchise általános címét tartalmazza, a lista nagy valószínűséggel egyértelműsítő entitásokat fog tartalmazni. De ha a kérelem a franchise egyik filmjének a pontos címét adja meg, a lista valószínűleg egyetlen domináns entitásból fog állni.

Az entitások lehetnek közismert személyek, például énekesek, színészek, sportolók, modellek stb.; helyek és nevezetességek, például a Mount Rainier vagy a Lincoln-emlékmű; valamint dolgok, például egy banán, goldendoodle kutya, könyv- vagy filmcím. Az entityPresentationInfo mező tartalmazza az entitás típusát azonosító mutatókat. Meghatározza például, hogy az entitás egy személy, film, állat vagy látnivaló. A lehetséges típusok listájáért lásd az entitások különböző típusait ismertető szakaszt.

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

Az alábbiakban egy olyan válasz látható, amely egy domináns és egy egyértelműsítő entitást tartalmaz.

{
    "_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"
        }]
    }
}

Az entitás tartalmaz egy name, description és image mezőt. Amikor megjeleníti ezeket a mezőket a felhasználók számára, meg kell adnia a forrásukat. A contractualRules mező az alkalmazandó forrásmegjelölések listáját tartalmazza. A szerződéses szabály azonosítja azt a mezőt, amelyre a forrásmegjelölés vonatkozik. A forrásmegjelölés alkalmazására vonatkozó információért lásd a forrásmegjelöléssel foglalkozó témakört.

"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"
}], ...

Az entitásinformáció (név, leírás és kép) megjelenítésekor a webSearchUrl mezőben lévő URL-címmel hivatkozni kell a Bing-keresés találati oldalára, amely tartalmazza az entitást.

Helyek keresése

A places mező egy LocalEntityAnswer objektum, amely a Place objektumok listáját tartalmazza (további információt az Entitástípusok című témakörben talál). A lista egy vagy több, a kérésre választ adó helyi entitást tartalmaz.

A helyek lehetnek éttermek, szállodák vagy különböző helyi vállalkozások. Az entityPresentationInfo mező tartalmazza a helyi entitás típusát azonosító mutatókat. Ilyen mutató lehet például a Place (hely), LocaLBusiness (helyi vállalkozás), Restaurant (étterem). Az egymást követő mutatók leszűkítik az entitás típusát. A lehetséges típusok listájáért lásd az entitások különböző típusait ismertető szakaszt.

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

Megjegyzés

Az entitásválaszok több piacot is támogatnak, de a „helyek” típusú válaszok csak az Egyesült Államokban található vállalkozásokat támogatják.

A helyfüggő entitáslekérdezésekben, amely például a közeli éttermekre vonatkozhat, a pontos találatokhoz ismerni kell a felhasználó tartózkodási helyét. A kérelemnek mindig használnia kell az X-Search-Location és az X-MSEdge-ClientIP fejléceket a felhasználó helyzetének meghatározásához. Ha a Bing úgy véli, hogy a lekérdezéshez érdemes lehet ismerni a felhasználó tartózkodási helyét, beállítja a QueryContextaskUserForLocation mezőjét igaz értékre.

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

A helytalálat tartalmazza a hely nevét, címét és telefonszámát, valamint az entitás webhelyének URL-címét. Az entitásadatok megjelenítésekor a webSearchUrl mezőben lévő URL-címmel hivatkozni kell a Bing-keresés találati oldalára, amely tartalmazza az entitást.

"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"
    }]
}

Megjegyzés

Ön vagy az Ön nevében eljáró harmadik fél nem használhatja, őrizheti meg, tárolhatja, gyorsítótárazhatja, oszthatja meg vagy terjesztheti az Entities API-ról szerzett adatokat tesztelés, fejlesztés, képzés, terjesztés vagy bármely nem Microsoft szolgáltatás vagy funkció elérhetővé tétele céljából.

Adatok forrásmegjelölése

A Bing Entity API által adott válaszok külső felek tulajdonában álló információkat tartalmaznak. Az Ön felelőssége az információk megfelelő használatának biztosítása, például azzal, hogy megfelel a felhasználói felületeihez és folyamataihoz igénybe vett Creative Commons-licencek feltételeinek.

Ha valamely válasz vagy eredmény tartalmazza az contractualRules, attributions vagy provider mezőket, az adatok forrását meg kell jelölnie. Ha a válasz egyiket sem tartalmazza, nem kell megjelölni a forrást. Ha a válasz a contractualRules mezőt, valamint az attributions és/vagy a provider mezőt tartalmazza, az adatok forrásának megjelöléséhez a szerződéses szabályokat kell alkalmaznia.

A következő példa bemutat egy entitást, amely tartalmazza a MediaAttribution (médiatartalmak forrásmegjelölésére vonatkozó) szerződéses szabályt, valamint egy képet, amely egy provider mezőt tartalmaz. A MediaAttribution szabály megállapítja, hogy a szabály a képre is vonatkozik, így a kép provider mezője figyelmen kívül hagyható, és helyette a MediaAttribution szabály alkalmazható a forrás megjelöléséhez.

"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
    },
    ...
}]

Ha egy szerződéses szabály tartalmazza a targetPropertyName mezőt, a szabály csak az érintett mezőkre vonatkozik. Ha nem, akkor a szabály a contractualRules mezőt tartalmazó szülőobjektumra vonatkozik.

A következő példában a LinkAttribution szabály tartalmazza a targetPropertyName mezőt, így a szabály a description mezőre vonatkozik. Az egyes mezőkre vonatkozó szabályoknál be kell szúrnia egy sort közvetlenül a célzott adatok után, amely a szolgáltató webhelyére mutató hivatkozást tartalmaz. A leírás forrásának megjelöléséhez például szúrjon be egy sort közvetlenül a leírás szövege után a szolgáltató webhelyére mutató hivatkozással (esetünkben ez a 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..."
                 },
            ...

Licencek forrásmegjelölése

Ha a szerződéses szabályok listája tartalmaz egy LicenseAttribution szabályt, a licencre vonatkozó tájékoztatást közvetlenül azután a tartalom után kell megjeleníteni, amelyre a licenc vonatkozik. A LicenseAttribution szabály a targetPropertyName mező segítségével azonosítja a tulajdonságot, amelyre a licenc vonatkozik.

Az alábbi példa tartalmaz egy LicenseAttribution szabályt.

Licenc hozzárendelése

A megjelenített licencadatok között kell lennie egy hivatkozásnak, amely a licenc információit tartalmazó webhelyre mutat. Általában a licenc nevét szokás hivatkozásként szerepeltetni. Például ha a tájékoztatás így szól: A szövegre a CC-BY-SA licenc vonatkozik, és a CC-BY-SA a licenc neve, a CC-BY-SA nevet érdemes hivatkozássá tenni.

Hivatkozások és szövegek forrásmegjelölése

A LinkAttribution és TextAttribution szabályokat általában az adatszolgáltató azonosítására alkalmazzuk. A targetPropertyName mező azonosítja a mezőt, amelyre a szabály vonatkozik.

A szolgáltató megjelölése érdekében szúrjon be egy sort közvetlenül a tartalom után, amelyre a forrásmegjelölés vonatkozik (például a célmező után). A sorban egyértelműen jelezni kell, hogy a szolgáltató az adatok forrása. Egy erre alkalmas megfogalmazás például a következő: „Az adatok forrása: contoso.com”. A LinkAttribution szabályoknál létre kell hoznia egy hivatkozást, amely a szolgáltató webhelyére mutat.

Az alábbi példa LinkAttribution és TextAttribution szabályokat is tartalmaz.

Hivatkozások és szövegek forrásmegjelölése

Médiatartalmak forrásmegjelölése

Ha az entitás képet tartalmaz, amelyet megjelenít, egy, a szolgáltató webhelyére mutató átkattintásos hivatkozást kell beszúrnia. Ha az entitás tartalmaz egy MediaAttribution szabályt, a szabály URL-címe alapján kell létrehozni az átkattintásos hivatkozást. Ha nem tartalmaz, használja a kép provider mezőjében lévő URL-címet.

Az alábbi példa egy kép provider mezőjét és szerződéses szabályait mutatja be. Mivel a példa tartalmazza a szerződéses szabályt, a kép provider mezőjét figyelmen kívül kell hagyni, és a MediaAttribution szabályt kell alkalmazni.

Médiamegjelenítés

Keresési vagy kereséshez hasonló funkciók

A Bing Web Search API-hoz hasonlóan a Bing Entity Search API is használható úgy, hogy csak a közvetlen felhasználói lekérdezésekre vagy keresésekre adjon ki eredményt, de úgy is beállítható, hogy egy alkalmazáson vagy funkción belüli olyan műveletekre is reagáljon, amelyek felhasználói keresési kérelemként is értelmezhetők. Szemléltetés céljából a következő esetek ilyen keresési vagy kereséshez hasonló funkciókra szolgálnak például.

A felhasználó megad egy lekérdezést közvetlenül egy alkalmazás keresőmezőjében.
A felhasználó kiválaszt egy meghatározott szöveget vagy képet, és „több információt” vagy „további információt” kér.
A felhasználó egy keresési robotot kérdez egy adott témáról.
A felhasználó egy meghatározott objektummal vagy entitással foglalkozik egy vizuális keresés során.

Amennyiben nem biztos benne, hogy egy művelet vagy szándék felfogható-e kereséshez hasonló funkcióként, ajánlott egyeztetni a Microsofttal.

Kérelmek szabályozása

A szolgáltatás és az előfizetés típusa határozza meg a másodpercenként futtatható lekérdezések számát (QPS). Mindenképpen gondoskodjon arról, hogy az alkalmazás tartalmazza a kvótán belül maradáshoz szükséges logikát. Ha eléri vagy túllépi a QPS határértékét, a kérés meghiúsul, és a rendszer HTTP 429-es állapotkódot ad vissza. A válasz a Retry-After fejlécet is tartalmazza, amely azt adja meg, hogy mennyi ideig kell várnia egy újabb kérés elküldése előtt.

Szolgáltatásmegtagadás kontra szabályozás

A szolgáltatás különbséget tesz a szolgáltatásmegtagadásos (DoS-) támadások és a QPS-eltérések között. Ha DoS-támadást feltételez, a kérés sikeres lesz (200 OK HTTP-állapotkóddal). A választörzs azonban üresen marad.

Következő lépések

Próbálja ki a Bing Entity Search API-val az entitások keresésének első lépéseit ismertető rövid útmutatót .

Entitások keresése a Bing Entity API-val

Keresési kifejezések ajánlása a Bing Autosuggest API-val

A Bing Entity Search API válasza

Helyek keresése

Adatok forrásmegjelölése

Licencek forrásmegjelölése

Hivatkozások és szövegek forrásmegjelölése

Médiatartalmak forrásmegjelölése

Keresési vagy kereséshez hasonló funkciók

Kérelmek szabályozása

Szolgáltatásmegtagadás kontra szabályozás

Következő lépések

További források