Bing Entity Search とはWhat is Bing Entity Search?

Bing Entity Search API は、Bing に検索クエリを送信して、エンティティと場所を含む検索結果を取得します。The Bing Entity Search API sends a search query to Bing and gets results that include entities and places. 場所の結果には、レストラン、ホテルやその他の地元企業が含まれます。Place results include restaurants, hotel, or other local businesses. クエリで地元企業の名前を指定、またはビジネスの種類 (近くのレストランなど) を要求すると、Bing は場所を返します。Bing returns places if the query specifies the name of the local business or asks for a type of business (for example, restaurants near me). クエリで有名な人や場所 (観光名所、州、国など)、またはものを指定すると、Bing はエンティティを返します。Bing returns entities if the query specifies well-known people, places (tourist attractions, states, countries, etc.), or things.

検索語句の補完と使用Suggesting & using search terms

ユーザーが検索語句を入力するための検索ボックスを用意する場合は、Bing Autosuggest API を使用することでエクスペリエンスが向上します。If you provide a search box where the user enters their search term, use the Bing Autosuggest API to improve the experience. この API は、検索語句をユーザーが入力している最中に、その一部分に基づいてクエリ文字列の候補を返します。The API returns suggested query strings based on partial search terms as the user types.

ユーザーが検索語句を入力した後、その語句を URL エンコードしたうえで、q クエリ パラメーターを設定します。After the user enters their search term, URL encode the term before setting the q query parameter. たとえば、ユーザーが「Marcus Appel」と入力した場合、qMarcus+Appel または Marcus%20Appel に設定します。For example, if the user enters Marcus Appel, set q to Marcus+Appel or Marcus%20Appel.

検索用語にスペル ミスが含まれていると、検索応答に QueryContext オブジェクトが含まれます。If the search term contains a spelling mistake, the search response includes a QueryContext object. このオブジェクトは元のスペルと Bing が検索に使用した修正済みのスペルを示します。The object shows the original spelling and the corrected spelling that Bing used for the search.

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

エンティティの要求Requesting entities

要求の例については、最初の要求を行うに関するページを参照してください。For an example request, see Making your first request.

応答The response

応答には、SearchResponse オブジェクトが含まれます。The response contains a SearchResponse object. Bing で関連するエンティティまたは場所が検出された場合、オブジェクトには entities フィールド、places フィールド、またはその両方が含まれます。If Bing finds an entity or place that's relevant, the object includes the entities field, places field, or both. それ以外の場合は、応答オブジェクトにはいずれのフィールドも含まれません。Otherwise, the response object does not include either field.

注意

エンティティの応答では複数の市場がサポートされますが、場所の応答では米国ビジネスの場所しかサポートされません。Entity responses support multiple markets, but the Places response supports only US Business locations.

entities フィールドは、Entity オブジェクトのリストを含む EntityAnswerオブジェクトです (value フィールドを参照)。The entities field is an EntityAnswer object that contains a list of Entity objects (see the value field). リストには、1 つの主要なエンティティ、複数のあいまいさ排除エンティティ、またはその両方が含まれている場合があります。The list may contain a single dominant entity, multiple disambiguation entities, or both.

主要なエンティティは、要求を満たす唯一のエンティティだと Bing が認識しているエンティティです (どのエンティティが要求を満たすかに関するあいまいさはありません)。A dominant entity is an entity that Bing believes is the only entity that satisfies the request (there is no ambiguity as to which entity satisfies the request). 複数のエンティティが要求を満たす可能性がある場合は、リストには複数のあいまいさ排除エンティティが含まれます。If multiple entities could satisfy the request, the list contains more than one disambiguation entity. たとえば、要求で映画シリーズの一般的なタイトルを使用している場合、リストにはあいまいさ排除エンティティが含まれる可能性が高くなります。For example, if the request uses the generic title of a movie franchise, the list likely contains disambiguation entities. しかし、要求でシリーズの特定のタイトルを指定した場合、リストには 1 つの主要なエンティティが含まれる可能性が高くなります。But, if the request specifies a specific title from the franchise, the list likely contains a single dominant entity.

エンティティには、有名な人物 (歌手、俳優、スポーツ選手、モデルなど)、場所やランドマーク (レーニア山やリンカーン記念館など)、もの (バナナ、ゴールデンドゥードル、本、映画のタイトルなど) が含まれます。Entities include well-known personalities such as singers, actors, athletes, models, etc.; places and landmarks such as Mount Rainier or Lincoln Memorial; and things such as a banana, goldendoodle, book, or movie title. entityPresentationInfo フィールドには、エンティティの型を識別するためのヒントが含まれています。The entityPresentationInfo field contains hints that identify the entity's type. たとえば、それが個人、映画、動物、またはアトラクションかどうかを識別します。For example, if it's a person, movie, animal, or attraction. 可能な型のリストについては、エンティティ型のセクションを参照してください。For a list of possible types, see Entity Types

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

主要なエンティティとあいまいさ排除エンティティを含む応答を次に示します。The following shows a response that includes a dominant and disambiguation entity.

{
    "_type": "SearchResponse",
    "queryContext": {
        "originalQuery": "Mount Rainier"
    },
    "entities": {
        "value": [{
            "contractualRules": [{
                "_type": "ContractualRules/LicenseAttribution",
                "targetPropertyName": "description",
                "mustBeCloseToContent": true,
                "license": {
                    "name": "CC-BY-SA",
                    "url": "http://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"
        }]
    }
}

このエンティティには、namedescriptionimage フィールドが含まれています。The entity includes a name, description, and image field. お使いのユーザー エクスペリエンスにこれらのフィールドを表示する場合は、これらに帰属を示す必要があります。When you display these fields in your user experience, you must attribute them. contractualRules フィールドには、適用する必要がある属性のリストが含まれています。The contractualRules field contains a list of attributions that you must apply. 契約上の規則は、属性が適用されるフィールドを識別します。The contractual rule identifies the field that the attribution applies to. 属性の適用に関する詳細は、属性のセクションを参照してください。For information about applying attribution, see Attribution.

"contractualRules": [{
    "_type": "ContractualRules/LicenseAttribution",
    "targetPropertyName": "description",
    "mustBeCloseToContent": true,
    "license": {
        "name": "CC-BY-SA",
        "url": "http://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"
}], ...

エンティティ情報 (名前、説明、イメージ) を表示する場合は、webSearchUrl フィールド内の URL を使用して、エンティティを含む Bing の検索結果ページにリンクする必要もあります。When you display the entity information (name, description, and image), you must also use the URL in the webSearchUrl field to link to the Bing search results page that contains the entity.

places フィールドは、Place オブジェクトのリストを含む LocalEntityAnswer オブジェクトです (value フィールドを参照)。The places field is a LocalEntityAnswer object that contains a list of Place objects (see the value field). このリストには、要求を満たす 1 つまたは複数のローカル エンティティが含まれます。The list contains one or more local entities that satisfy the request.

場所には、レストラン、ホテル、または地元企業が含まれます。Places include restaurant, hotels, or local businesses. entityPresentationInfo フィールドには、ローカル エンティティの型を識別するためのヒントが含まれています。The entityPresentationInfo field contains hints that identify the local entity's type. リストには、Place、LocalBusiness、Restaurant などのヒントのリストが含まれています。The list contains a list of hints such as Place, LocalBusiness, Restaurant. 配列内の連続する各ヒントにより、エンティティの型が絞り込まれます。Each successive hint in the array narrows the entity's type. 可能な型のリストについては、エンティティ型のセクションを参照してください。For a list of possible types, see Entity Types

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

注意

エンティティの応答では複数の市場がサポートされますが、場所の応答では米国ビジネスの場所しかサポートされません。Entity responses support multiple markets, but the Places response supports only US Business locations.

近くのレストランなどのローカル対応エンティティ クエリでは、正確な結果を提供するためにユーザーの場所を提供する必要があります。Local aware entity queries such as restaurant near me require the user's location to provide accurate results. 要求では常に X-Search-Location と X-MSEdge-ClientIP のヘッダーを使用して、ユーザーの場所を指定する必要があります。Your requests should always use the X-Search-Location and X-MSEdge-ClientIP headers to specify the user's location. Bing では、ユーザーの場所をクエリに使用するメリットが認められると、QueryContextaskUserForLocation フィールドが true に設定されます。If Bing thinks the query would benefit from the user's location, it sets the askUserForLocation field of QueryContext to true.

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

場所の結果には、場所の名前、住所、電話番号、エンティティの Web サイトの URL が含まれます。A place result includes the place's name, address, telephone number, and URL to the entity's website. エンティティ情報を表示する場合は、webSearchUrl フィールド内の URL を使用して、エンティティを含む Bing の検索結果ページにリンクする必要もあります。When you display the entity information, you must also use the URL in the webSearchUrl field to link to the Bing search results page that contains the entity.

"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 以外のサービスまたは機能のテスト、開発、トレーニング、頒布、または提供を目的として利用、保持、保存、キャッシュ、共有、または配布することは認められません。You, or a third party on your behalf, may not use, retain, store, cache, share, or distribute any data from the Entities API for the purpose of testing, developing, training, distributing or making available any non-Microsoft service or feature.

データの属性Data attribution

Bing Entity API の応答には、第三者が所有する情報が含まれます。Bing Entity API responses contain information owned by third parties. お客様は、ユーザー エクスペリエンスで利用するクリエイティブ コモンズ ライセンスがあればそれを順守するなど、情報を適切に利用する責任を負います。You are responsible to ensure your use is appropriate, for example by complying with any creative commons license your user experience may rely on.

回答または結果に contractualRulesattributionsprovider のいずれかのフィールドが含まれている場合、データをそれらの帰属を示す必要があります。If an answer or result includes the contractualRules, attributions, or provider fields, you must attribute the data. 回答にこれらのいずれのフィールドも含まれていない場合は、属性は必要ありません。If the answer does not include any of these fields, no attribution is required. 回答に contractualRules フィールドと、attributions フィールドまたは provider フィールド (またはその両方) が含まれている場合は、契約上の規則を使用してデータがそれらの帰属を示す必要があります。If the answer includes the contractualRules field and the attributions and/or provider fields, you must use the contractual rules to attribute the data.

次の例では、MediaAttribution タイプの契約規則を含むエンティティと、provider フィールドを含む画像を示しています。The following example shows an entity that includes a MediaAttribution contractual rule and an Image that includes a provider field. この MediaAttribution 規則では、規則の対象として画像を指定しています。このため、帰属の表示にあたっては画像の provider フィールドが無視され、代わりに MediaAttribution 規則が使用されることになります。The MediaAttribution rule identifies the image as the target of the rule, so you'd ignore the image's provider field and instead use the MediaAttribution rule to provide attribution.

"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 フィールドが含まれている場合、規則は対象のフィールドにのみ適用されます。If a contractual rule includes the targetPropertyName field, the rule applies only to the targeted field. 含まれていない場合は、規則は contractualRules フィールドを含む親オブジェクトに適用されます。Otherwise, the rule applies to the parent object that contains the contractualRules field.

次の例では、LinkAttribution 規則に targetPropertyName フィールドが含まれているため、description フィールドに規則が適用されます。In the following example, the LinkAttribution rule includes the targetPropertyName field, so the rule applies to the description field. 特定のフィールドに適用される規則の場合、プロバイダーの Web サイトへのハイパーリンクを含む対象となるデータの直後に 1 行含める必要があります。For rules that apply to specific fields, you must include a line immediately following the targeted data that contains a hyperlink to the provider's website. たとえば、説明の帰属を示すには、プロバイダーの Web サイト上のデータへのハイパーリンクを含む説明テキストの直後に 1 行含めます。このケースでは、contoso.com へのリンクを作成します。For example, to attribute the description, include a line immediately following the description text that contains a hyperlink to the data on the provider's website, in this case create a link to 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..."
                 },
            ...

ライセンスの属性License attribution

契約上の規則のリストに LicenseAttribution 規則が含まれている場合、ライセンスが適用されるコンテンツの直後の行に通知を表示する必要があります。If the list of contractual rules includes a LicenseAttribution rule, you must display the notice on the line immediately following the content that the license applies to. LicenseAttribution 規則では、ライセンスが適用されるプロパティを特定するために targetPropertyName フィールドを使用します。The LicenseAttribution rule uses the targetPropertyName field to identify the property that the license applies to.

LicenseAttribution 規則を含む例を次に示します。The following shows an example that includes a LicenseAttribution rule.

ライセンスの帰属表示

表示するライセンス通知には、ライセンスに関する情報を掲載している Web サイトへのハイパーリンクを含める必要があります。The license notice that you display must include a hyperlink to the website that contains information about the license. 通常は、ライセンスの名前をハイパーリンクにします。Typically, you make the name of the license a hyperlink. たとえば、通知が CC-BY-SA ライセンスの下のテキストで、CC-BY-SA がライセンスの名前の場合、CC-BY-SA がハイパーリンクになります。For example, if the notice is Text under CC-BY-SA license and CC-BY-SA is the name of the license, you would make CC-BY-SA a hyperlink.

LinkAttributionTextAttribution の規則は、通常、データのプロバイダーを識別するために使用されます。The LinkAttribution and TextAttribution rules are typically used to identify the provider of the data. targetPropertyName フィールドは、規則が適用されるフィールドを特定するためのものです。The targetPropertyName field identifies the field that the rule applies to.

プロバイダーの帰属を示すには属性を適用するコンテンツ (対象となるフィールドなど) の直後に 1 行含めます。To attribute the providers, include a line immediately following the content that the attributions apply to (for example, the targeted field). この行は、プロバイダーがデータのソースであることを示すため、明確にラベル付けする必要があります。The line should be clearly labeled to indicate that the providers are the source of the data. たとえば、"データ元: contoso.com" のようにします。For example, "Data from: contoso.com". LinkAttribution 規則の場合、プロバイダーの Web サイトへのハイパーリンクを作成する必要があります。For LinkAttribution rules, you must create a hyperlink to the provider's website.

LinkAttribution および TextAttribution の規則を含む例を次に示します。The following shows an example that includes LinkAttribution and TextAttribution rules.

テキスト属性のリンク

メディアの属性Media attribution

エンティティにイメージが含まれていて、それを表示する場合は、プロバイダーの Web サイトへのクリックスルー リンクを提供する必要があります。If the entity includes an image and you display it, you must provide a click-through link to the provider's website. エンティティに MediaAttribution 規則が含まれている場合、その規則の URL を使用してクリックスルー リンクを作成します。If the entity includes a MediaAttribution rule, use the rule's URL to create the click-through link. 含まれていない場合は、画像の provider フィールドに含まれる URL を使用してクリックスルー リンクを作成します。Otherwise, use the URL included in the image's provider field to create the click-through link.

イメージの provider フィールドと契約上の規則を含む例を次に示します。The following shows an example that includes an image's provider field and contractual rules. 例には契約上の規則が含まれているため、イメージの provider フィールドを無視して、MediaAttribution 規則を適用します。Because the example includes the contractual rule, you ignore the image's provider field and apply the MediaAttribution rule.

メディアの属性

検索または検索と同様のエクスペリエンスSearch or search-like experience

Bing Web Search API と同じく、Entity Search API は、直接ユーザー クエリまたは検索の結果として、またはアプリまたはエクスペリエンス内のユーザーの検索結果として論理的に解釈できるアクションの結果としてのみ使用できます。Just like with Bing Web Search API, the Bing Entity Search API may only be used as a result of a direct user query or search, or as a result of an action within an app or experience that logically can be interpreted as a user’s search request. わかりやすくするため、許容できる検索または検索に似たエクスペリエンスの例をいくつか次に示します。For illustration purposes, the following are some examples of acceptable search or search-like experiences.

  • ユーザーがアプリ内の検索ボックスに直接クエリを入力するUser enters a query directly into a search box in an app
  • ユーザーが特定のテキストまたはイメージを選択し、"詳細" または "追加情報" を要求するUser selects specific text or image and requests “more information” or “additional information”
  • ユーザーが特定のトピックに関する検索ボットを要求するUser asks a search bot about a particular topic
  • ユーザーが Visual Search の種類のシナリオで、特定のオブジェクトまたはエンティティについて詳しく説明するUser dwells on a particular object or entity in a visual search type scenario

エクスペリエンスが検索と同様のエクスペリエンスと見なせるかどうかわからない場合は、Microsoft に確認することをお勧めします。If you are not sure if your experience can be considered a search-like experience, it is recommended that you check with Microsoft.

スロットル リクエストThrottling requests

サービスとサブスクリプションの種類によって、1 秒あたりのクエリ数 (QPS) が決まります。The service and your subscription type determine the number of queries per second (QPS) that you can make. アプリケーションに、クォータ内に収めるロジックを含めるようにしてください。Make sure your application includes the logic to stay within your quota. QPS の上限に達するか超えた場合、要求は失敗し、HTTP 429 状態コードが返されます。If the QPS limit is met or exceeded, the request fails and an HTTP 429 status code is returned. 応答には、Retry-After ヘッダーが含まれています。これは、別の要求を送信できるようになるまでに待機する必要がある時間を示します。The response includes the Retry-After header, which indicates how long you must wait before sending another request.

サービス拒否とスロットリングDenial-of-service versus throttling

このサービスは、サービス拒否 (DoS) 攻撃と QPS 違反を区別しています。The service makes a differentiation between a denial-of-service (DoS) attack and a QPS violation. サービスが DoS 攻撃を疑っている場合、要求は成功します (HTTP 状態コードは 200 OK)。If the service suspects a DoS attack, the request succeeds (HTTP status code is 200 OK). しかし、応答の本文は空になります。However, the body of the response is empty.

次の手順Next steps

実際に要求を送信してみるには、最初の要求を行うに関するページを参照してください。To get started quickly with your first request, see Making Your First Request.

Bing Entity Search API v7 リファレンスを活用してください。Familiarize yourself with the Bing Entity Search API v7 reference. リファレンスには、検索結果を要求する際に使用するヘッダーとクエリ パラメーターが記載されています。The reference contains the headers and query parameters that you use to request search results. また、応答オブジェクトの定義も記載されています。It also includes definitions of the response objects.

検索ボックスのユーザー エクスペリエンスを高めるには、Bing Autosuggest API に関するページを参照してください。To improve your search box user experience, see Bing Autosuggest API. ユーザーによって検索語が入力されている最中に、この API を呼び出すことで、他のユーザーによって使用された関連性の高い検索語を取得できます。As the user enters their query term, you can call this API to get relevant query terms that were used by others.

検索結果の使用に関するルールを逸脱しないよう、Bing の使用上および表示上の要件に関するページを必ず読んでください。Be sure to read Bing Use and Display Requirements so you don't break any of the rules about using the search results.