Wyszukiwanie jednostek za pomocą interfejsu API jednostek Bing

Ostrzeżenie

30 października 2020 r. interfejsy API Wyszukiwanie Bing zostały przeniesione z usług Azure AI do usług Wyszukiwanie Bing Services. Ta dokumentacja jest dostarczana tylko do celów referencyjnych. Aby uzyskać zaktualizowaną dokumentację, zobacz dokumentację interfejsu API wyszukiwania Bing. Aby uzyskać instrukcje dotyczące tworzenia nowych zasobów platformy Azure na potrzeby wyszukiwania Bing, zobacz Tworzenie zasobu Wyszukiwanie Bing za pomocą Azure Marketplace.

Sugerowanie terminów wyszukiwania za pomocą interfejsu API automatycznego sugerowania Bing

Jeśli udostępniasz pole wyszukiwania, w którym użytkownik wprowadza wyszukiwany termin, użyj interfejsu API automatycznego sugerowania Bing w celu ulepszenia jego działania. Interfejs API zwraca sugerowane ciągi zapytań na podstawie częściowych wyszukiwanych terminów w miarę wpisywania ich przez użytkownika.

Gdy użytkownik wprowadzi wyszukiwany termin, zakoduj go w formacie URL przed ustawieniem parametru zapytania q. Jeśli na przykład użytkownik wprowadzi termin Marcus Appel, należy ustawić parametr q na Marcus+Appel lub Marcus%20Appel.

Jeśli wyszukiwany termin zawiera błąd pisowni, odpowiedź wyszukiwania zawiera obiekt QueryContext. Obiekt ten zawiera pierwotną pisownię oraz poprawioną pisownię użytą przez usługę Bing podczas wyszukiwania.

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

Odpowiedź interfejsu API wyszukiwania jednostek Bing

Odpowiedź interfejsu API zawiera obiekt SearchResponse. Jeśli wyszukiwarka Bing znajdzie dopasowane jednostki lub miejsca, ten obiekt będzie zawierał pole entities, pole places lub oba te pola. W przeciwnym razie obiekt odpowiedzi nie będzie zawierał żadnego z tych pól.

Uwaga

Odpowiedzi dotyczące jednostek są obsługiwane na wielu rynkach, ale odpowiedzi dotyczące miejsc są obsługiwane tylko w przypadku lokalizacji firmowych w USA.

Pole entities to obiekt EntityAnswer zawierający listę obiektów Entity (zobacz pole value). Lista może zawierać jedną jednostkę dominującą, wiele jednostek uściślających lub oba te elementy.

Jednostka dominująca jest zwracana, gdy zostanie uznana przez usługę Bing za jedyną jednostkę spełniającą kryteria żądania (można jednoznacznie stwierdzić, jaka jednostka spełnia kryteria żądania). Jeśli kryteria żądania spełnia wiele jednostek, lista zawiera większą liczbę jednostek uściślających. Na przykład jeśli w żądaniu użyto ogólnego tytułu serii filmów, lista będzie najprawdopodobniej zawierała jednostki uściślające. Jeśli jednak w żądaniu użyto tytułu konkretnego filmu z serii, lista będzie najprawdopodobniej zawierała jedną jednostkę dominującą.

Jednostki mogą obejmować znane osobistości, na przykład piosenkarzy, aktorki, sportowców, modelki itp.; miejsca i obiekty, takie jak Mount Rainier czy Mauzoleum Abrahama Lincolna; a także inne obiekty, takie jak banan, goldendoodle albo tytuł książki lub filmu. Pole entityPresentationInfo zawiera wskazówki określające typ jednostki. Mogą wskazywać na przykład, że jest to osoba, film, zwierzę lub atrakcja. Aby zapoznać się z listą możliwych typów, zobacz Entity types (Typy jednostek)

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

Poniżej przedstawiono odpowiedź zawierającą jednostkę dominującą i uściślającą.

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

Jednostka zawiera pola name (nazwa), description (opis) i image (obraz). W przypadku wyświetlania tych pól w środowisku użytkownika konieczne jest podanie ich autorstwa lub źródła. Pole contractualRules (reguły umowne) zawiera listę wymaganych przypisań autorstwa. Reguła umowna określa również pole, którego dotyczy dane przypisanie. Aby uzyskać informacje dotyczące przypisywania autorstwa, zobacz Określanie autorstwa danych.

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

W przypadku wyświetlania informacji dotyczących jednostki (nazwy, opisu i obrazu) należy również użyć adresu URL w polu webSearchUrl, aby dodać link do zawierającej tę jednostkę strony wyników wyszukiwania w usłudze Bing.

Znajdowanie miejsc

Pole places to obiekt LocalEntityAnswer zawierający listę obiektów Place. Zobacz Entity Types (Typy jednostek), aby uzyskać więcej informacji. Lista zawiera co najmniej jedną lokalną jednostkę spełniającą kryteria żądania.

Miejsca to między innymi restauracje, hotele, czy lokalne firmy. Pole entityPresentationInfo zawiera wskazówki określające typ jednostki lokalnej. Lista zawiera listę wskazówek, takich jak Place (miejsce), LocalBusiness (lokalna firma), czy Restaurant (restauracja). Każda kolejne wskazówka w tablicy powoduje zawężenie typu jednostki. Aby zapoznać się z listą możliwych typów, zobacz Entity types (Typy jednostek)

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

Uwaga

Odpowiedzi dotyczące jednostek są obsługiwane na wielu rynkach, ale odpowiedzi dotyczące miejsc są obsługiwane tylko w przypadku lokalizacji firmowych w USA.

Zapytania dotyczące jednostek uwzględniające lokalizację, na przykład restaurants near me (restauracje w pobliżu), wymagają lokalizacji użytkownika do znalezienia dokładnych wyników. W zapytaniach należy zawsze używać nagłówków X-Search-Location i X-MSEdge-ClientIP w celu określenia lokalizacji użytkownika. Jeśli usługa Bing uzna, że użycie lokalizacji użytkownika będzie korzystne podczas wykonywania zapytania, ustawi w polu askUserForLocation obiektu QueryContext wartość true.

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

Wynik dotyczący miejsca zawiera nazwę tego miejsca, jego adres, numer telefonu oraz adres URL jego witryny internetowej. W przypadku wyświetlania informacji dotyczących jednostki należy również użyć adresu URL w polu webSearchUrl, aby dodać link do zawierającej tę jednostkę strony wyników wyszukiwania w usłudze 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"
    }]
}

Uwaga

Użytkownik ani żaden inny podmiot w jego imieniu nie może używać, zachowywać, przechowywać, buforować, udostępniać ani rozpowszechniać żadnych danych z interfejsu API wyszukiwania jednostek do celów testowania, opracowywania, rozpowszechniania lub udostępniania jakiejkolwiek usługi lub funkcji firmy innej niż Microsoft.

Określanie autorstwa danych

Odpowiedzi z interfejsu API wyszukiwania jednostek Bing zawierają informacje, których właścicielem są inne podmioty. Użytkownik odpowiada za korzystanie z usługi w sposób właściwy, na przykład poprzez przestrzeganie licencji Creative Commons, z których mogą korzystać elementy środowiska użytkownika.

Jeśli odpowiedź lub wynik zawiera pola contractualRules, attributions lub provider, należy podać autorstwo danych. Jeśli odpowiedź nie zawiera żadnego z tych pól, podanie autorstwa danych nie jest wymagane. Jeśli odpowiedź zawiera pole contractualRules oraz pola attributions i/lub provider, należy zastosować reguły umowne w celu określenia autorstwa danych.

W poniższym przykładzie pokazano jednostkę, która zawiera regułę umowną MediaAttribution i obraz, który zawiera pole provider. Reguła MediaAttribution identyfikuje obraz jako obiekt docelowy reguły, a więc możesz zignorować pole provider obrazu, i zastosować regułę MediaAttribution w celu określenia autorstwa.

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

Jeśli reguła umowna zawiera pole targetPropertyName, reguła dotyczy tylko pola docelowego. W przeciwnym razie ta reguła dotyczy obiektu nadrzędnego, który zawiera pole contractualRules.

W poniższym przykładzie reguła LinkAttribution zawiera pole targetPropertyName, a więc reguła dotyczy pola description. W przypadku reguł, które dotyczą konkretnych pól, po danych docelowych musisz umieścić wiersz zawierający hiperlink do witryny internetowej dostawcy. Na przykład aby podać autorstwo opisu, po tekście opisu należy dołączyć wiersz zawierający hiperlink do danych w witrynie internetowej dostawcy — w tym przypadku link do witryny 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..."
                 },
            ...
  

Określanie licencji

Jeśli lista reguł umownych zawiera regułę LicenseAttribution, należy w wierszu następującym tuż po zawartości objętej licencją dodać odpowiednią informację. Reguła LicenseAttribution korzysta z pola targetPropertyName, aby określić właściwość, której dotyczy licencja.

Poniżej pokazano przykład, który zawiera regułę LicenseAttribution.

Wyświetlana informacja dotycząca licencji musi zawierać hiperlink do witryny internetowej, która zawiera informacje dotyczące licencji. Najczęściej hiperlinkiem jest nazwa licencji. Na przykład jeśli komunikat brzmi Text under CC-BY-SA license (Tekst w ramach licencji CC-BY-SA), a CC-BY-SA to nazwa licencji, hiperlinkiem będzie ciąg „CC-BY-SA”.

Określanie autorstwa linków i tekstu

Reguły LinkAttribution i TextAttribution są zwykle używane do identyfikowania dostawcy danych. Pole targetPropertyName określa pole, którego dotyczy reguła.

Aby określić dostawców, należy dodać odpowiedni wiersz tuż po zawartości, której dotyczy (na przykład po polu docelowym). Ten wiersz powinien być czytelnie oznaczony, aby wskazać, że określeni dostawcy są źródłem danych. Na przykład „Źródło danych: contoso.com”. W przypadku reguł LinkAttribution, należy utworzyć hiperlink do witryny internetowej dostawcy.

Poniżej pokazano przykład, który zawiera reguły LinkAttribution i TextAttribution.

Określanie autorstwa multimediów

Jeśli jednostka zawiera obraz, który wyświetlasz, musisz dołączyć link do witryny dostawcy, który można kliknąć. Jeśli jednostka zawiera regułę MediaAttribution, należy do utworzenia tego linku użyć adresu URL określonego przez regułę. W przeciwnym razie do utworzenia tego linku użyj adresu URL zawartego w polu provider obrazu.

Poniżej przedstawiono przykład, który zawiera pole provider obrazu i reguły umowne. Ponieważ przykład zawiera reguły umowne, należy zignorować pole provider obrazu i zastosować regułę MediaAttribution.

Środowisko wyszukiwania lub czynności podobnych do wyszukiwania

Tak samo jak w przypadku interfejsu API wyszukiwania w sieci Web Bing, interfejs API wyszukiwania jednostek Bing może być używany tylko w wyniku wykonania zapytania lub wyszukiwania bezpośrednio przez użytkownika lub w wyniku wykonania w aplikacji lub środowisku czynności, którą można logicznie zinterpretować jako żądanie wyszukiwania użytkownika. W celach ilustracyjnych przedstawiono poniżej kilka przykładów akceptowalnych sytuacji wyszukiwania lub czynności podobnych do wyszukiwania.

• Użytkownik wprowadza zapytanie bezpośrednio w polu wyszukiwania w aplikacji.
• Użytkownik wybiera określony tekst lub obraz, a następnie wybiera opcję „więcej informacji” lub „dodatkowe informacje”.
• Użytkownik zadaje botowi wyszukiwania pytanie dotyczące określonego tematu.
• Użytkownik zatrzymuje się na obiekcie lub jednostce w scenariuszu wyszukiwania wizualnego.

Jeśli nie masz pewności, czy Twoje środowisko można uznać za środowisko czynności podobnych do wyszukiwania, zalecamy kontakt z firmą Microsoft.

Ograniczanie żądań

Usługa i typ subskrypcji decydują o liczbie zapytań, które możesz wykonywać na sekundę. Upewnij się, że Twoja aplikacja zawiera logikę niezbędną do nieprzekraczania tego limitu przydziału. W przypadku osiągnięcia lub przekroczenia limitu liczby zapytań na sekundę żądanie kończy się niepowodzeniem i jest zwracany kod stanu HTTP 429. Odpowiedź zawiera nagłówek Retry-After, która wskazuje, jak długo należy zaczekać przed wysłaniem kolejnego żądania.

Odmowa usługi a ograniczanie przepustowości

Usługa odróżnia atak typu „odmowa usługi” (DoS) od naruszenia liczby zapytań na sekundę. Jeśli usługa podejrzewa atak DoS, żądanie kończy się powodzeniem (kod stanu HTTP to 200 OK). Treść odpowiedzi jest jednak pusta.

Następne kroki

• Użyj tego poradnika Szybki start, aby zacząć wyszukiwać jednostki za pomocą interfejsu API wyszukiwania jednostek Bing.