クイックスタート:Bing Entity Search クライアントライブラリを使用する

[アーティクル]
03/06/2020

警告

2020 年 10 月 30 日に、Bing Search API は Azure AI サービスから Bing Search サービスに移行されました。このドキュメントは、参考用としてのみ提供されています。更新されたドキュメントについては、Bing search API のドキュメントを参照してください。 Bing 検索用の新しい Azure リソースを作成する手順については、「Azure Marketplace から Bing Search リソースを作成する」を参照してください。

このクイックスタートは、Bing Entity Search の C# 用クライアントライブラリからエンティティを検索するのに使用できます。 Bing Entity Search の REST API はほとんどのプログラミング言語に対応していますが、このクライアントライブラリを使用すると、サービスをお使いのアプリケーションに簡単に統合することができます。このサンプルのソースコードは、GitHub にあります。

前提条件

Visual Studio 2017 またはそれ以降の任意のエディション。
NuGet パッケージとして入手できる Json.NET フレームワーク。
Linux/macOS を使用している場合、このアプリケーションは Mono を使用して実行できます。
Bing News Search SDK NuGet パッケージ。このパッケージをインストールすると、次のものもインストールされます。
- Microsoft.Rest.ClientRuntime
- Microsoft.Rest.ClientRuntime.Azure
- Newtonsoft.Json

Bing Entity Search クライアントライブラリをお使いの Visual Studio プロジェクトに追加するには、ソリューションエクスプローラーの [NuGet パッケージの管理] オプションを使用して、パッケージを追加します。

Azure リソースを作成する

次のいずれかの Azure リソースを作成して、Bing Entity Search API の使用を開始します。

Bing Entity Search のリソース

ご自身でリソースを削除するまでは Azure portal からご利用いただけます。
Free 価格レベルを使ってサービスを試用し、後から運用環境用の有料レベルにアップグレードします。
Bing Entity Search は、Bing Search v7 リソースの有料レベルでも提供されています。

マルチサービスリソース

ご自身でリソースを削除するまでは Azure portal からご利用いただけます。
複数の Azure AI サービス全体で同じキーとエンドポイントをアプリケーションに使用します。

アプリケーションを作成して初期化する

Visual Studio で、新しい C# コンソールソリューションを作成します。次に、メインコードファイルに次の内容を追加します。

using System;
using System.Linq;
using System.Text;
using Microsoft.Azure.CognitiveServices.Search.EntitySearch;
using Microsoft.Azure.CognitiveServices.Search.EntitySearch.Models;
using Newtonsoft.Json;

クライアントを作成して検索要求を送信する

新しい検索クライアントを作成します。新しい ApiKeyServiceClientCredentials を作成して、サブスクリプションキーを追加します。
```
var client = new EntitySearchClient(new ApiKeyServiceClientCredentials("YOUR-ACCESS-KEY"));
```
クライアントの Entities.Search() 関数を使用して、クエリを検索します。
```
var entityData = client.Entities.Search(query: "Satya Nadella");
```

エンティティの説明を取得して表示する

API で検索結果が返された場合は、entityData からメインエンティティを取得します。

var mainEntity = entityData.Entities.Value.Where(thing => thing.EntityPresentationInfo.EntityScenario == EntityScenario.DominantEntity).FirstOrDefault();

メインエンティティの説明を表示します
```
Console.WriteLine(mainEntity.Description);
```

次のステップ

単一ページの Web アプリの作成

Bing Entity Search API とは

このクイックスタートは、Bing Entity Search の Java 用クライアントライブラリからエンティティを検索するのに使用できます。 Bing Entity Search の REST API はほとんどのプログラミング言語に対応していますが、このクライアントライブラリを使用すると、サービスをお使いのアプリケーションに簡単に統合することができます。このサンプルのソースコードは、GitHub にあります。

前提条件

Java Development Kit (JDK)
Bing Entity Search の Java 用クライアントライブラリ

Bing Entity Search クライアントライブラリの依存関係は、Maven、Gradle、またはその他の依存関係管理システムを使用してをインストールできます。 Maven POM ファイルには、次の宣言が必要です。

<dependency>
  <groupId>com.microsoft.azure.cognitiveservices</groupId>
  <artifactId>azure-cognitiveservices-entitysearch</artifactId>
  <version>1.0.2</version>
</dependency>

Azure リソースを作成する

次のいずれかの Azure リソースを作成して、Bing Entity Search API の使用を開始します。

Bing Entity Search のリソース

ご自身でリソースを削除するまでは Azure portal からご利用いただけます。
Free 価格レベルを使ってサービスを試用し、後から運用環境用の有料レベルにアップグレードします。
Bing Entity Search は、Bing Search v7 リソースの有料レベルでも提供されています。

マルチサービスリソース

ご自身でリソースを削除するまでは Azure portal からご利用いただけます。
複数の Azure AI サービス全体で同じキーとエンドポイントをアプリケーションに使用します。

プロジェクトの作成と初期化

普段使用している IDE またはエディターで新しい Java プロジェクトを作成し、以下のライブラリをインポートします。

import com.microsoft.azure.cognitiveservices.entitysearch.*;
import com.microsoft.azure.cognitiveservices.entitysearch.implementation.EntitySearchAPIImpl;
import com.microsoft.azure.cognitiveservices.entitysearch.implementation.SearchResponseInner;
import com.microsoft.rest.credentials.ServiceClientCredentials;
import okhttp3.Interceptor;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

サブスクリプションキーの変数を作成します
```
String subscriptionKey = "your-key-here"
```

検索クライアントを作成する

dominantEntityLookup クライアントを実装します。これには API エンドポイントと ServiceClientCredentials クラスのインスタンスが必要となります。以下のグローバルエンドポイントを使用するか、Azure portal に表示される、リソースのカスタムサブドメインエンドポイントを使用できます。
```
public static EntitySearchAPIImpl getClient(final String subscriptionKey) {
    return new EntitySearchAPIImpl("https://api.cognitive.microsoft.com/bing/v7.0/",
            new ServiceClientCredentials() {
            //...
            }
)};
```
ServiceClientCredentials を実装するには、次の手順に従います。
1. OkHttpClient.Builder オブジェクトをパラメーターとして applyCredentialsFilter() 関数をオーバーライドします。
```
//...
new ServiceClientCredentials() {
        @Override
        public void applyCredentialsFilter(OkHttpClient.Builder builder) {
        //...
        }
//...
```
2. applyCredentialsFilter() 内で builder.addNetworkInterceptor() を呼び出します。新しい Interceptor オブジェクトを作成し、その intercept() メソッドをオーバーライドして、Chain インターセプターオブジェクトを受け取るようにします。
```
//...
builder.addNetworkInterceptor(
    new Interceptor() {
        @Override
        public Response intercept(Chain chain) throws IOException {
        //...    
        }
    });
///...
```
3. intercept 関数内に、要求のための変数を作成します。 Request.Builder() を使用して要求を作成します。 Ocp-Apim-Subscription-Key ヘッダーにサブスクリプションキーを追加し、要求オブジェクトで chain.proceed() を返します。
```
//...
public Response intercept(Chain chain) throws IOException {
    Request request = null;
    Request original = chain.request();
    Request.Builder requestBuilder = original.newBuilder()
            .addHeader("Ocp-Apim-Subscription-Key", subscriptionKey);
    request = requestBuilder.build();
    return chain.proceed(request);
}
//...
```

要求を送信して応答を受信する

サブスクリプションキーを使用して検索クライアントの新しいインスタンスを作成します。 client.entities().search() を使用して検索クエリ satya nadella に対する検索要求を送信し、応答を受け取ります。
```
EntitySearchAPIImpl client = getClient(subscriptionKey);
SearchResponseInner entityData = client.entities().search(
        "satya nadella", null, null, null, null, null, null, "en-us", null, null, SafeSearch.STRICT, null);
```

エンティティが返された場合は、リストに変換します。それを反復処理し、主要なエンティティを表示します。

if (entityData.entities().value().size() > 0){
    // Find the entity that represents the dominant entity
    List<Thing> entries = entityData.entities().value();
    Thing dominateEntry = null;
    for(Thing thing : entries) {
        if(thing.entityPresentationInfo().entityScenario() == EntityScenario.DOMINANT_ENTITY) {
            System.out.println("\r\nSearched for \"Satya Nadella\" and found a dominant entity with this description:");
            System.out.println(thing.description());
            break;
        }
    }
}

次のステップ

シングルページ Web アプリの作成

Bing Entity Search API とは

このクイックスタートは、Bing Entity Search の JavaScript 用クライアントライブラリからエンティティを検索するのに使用できます。 Bing Entity Search の REST API はほとんどのプログラミング言語に対応していますが、このクライアントライブラリを使用すると、サービスをお使いのアプリケーションに簡単に統合することができます。このサンプルのソースコードは、GitHub にあります。

前提条件

最新バージョンの Node.js。
Bing Entity Search SDK for JavaScript
- インストールするには、npm install @azure/cognitiveservices-entitysearch を実行します
クライアントを認証するための CognitiveServicesCredentials クラス (@azure/ms-rest-azure-js パッケージに含まれています)。
- インストールするには、npm install @azure/ms-rest-azure-js を実行します

Azure リソースを作成する

次のいずれかの Azure リソースを作成して、Bing Entity Search API の使用を開始します。

Bing Entity Search のリソース

ご自身でリソースを削除するまでは Azure portal からご利用いただけます。
Free 価格レベルを使ってサービスを試用し、後から運用環境用の有料レベルにアップグレードします。
Bing Entity Search は、Bing Search v7 リソースの有料レベルでも提供されています。

マルチサービスリソース

ご自身でリソースを削除するまでは Azure portal からご利用いただけます。
複数の Azure AI サービス全体で同じキーとエンドポイントをアプリケーションに使用します。

アプリケーションを作成して初期化する

好みの IDE またはエディターで新しい JavaScript ファイルを作成し、次の要件を追加します。

const CognitiveServicesCredentials = require('@azure/ms-rest-azure-js').CognitiveServicesCredentials;
const EntitySearchAPIClient = require('@azure/cognitiveservices-entitysearch');

サブスクリプションキーを使用して、CognitiveServicesCredentials のインスタンスを作成します。その後、それで検索クライアントのインスタンスを作成します。
```
let credentials = new CognitiveServicesCredentials('YOUR-ACCESS-KEY');
let entitySearchApiClient = new EntitySearchAPIClient(credentials);
```

要求を送信して応答を受信する

entitiesOperations.search() を使用してエンティティの検索要求を送信します。応答を受け取った後、queryContext、返された結果の数、最初の結果の説明を表示します。

entitySearchApiClient.entitiesOperations.search('seahawks').then((result) => {
    console.log(result.queryContext);
    console.log(result.entities.value);
    console.log(result.entities.value[0].description);
}).catch((err) => {
    throw err;
});

次のステップ

単一ページの Web アプリの作成

Bing Entity Search API とは

このクイックスタートは、Bing Entity Search の Python 用クライアントライブラリからエンティティを検索するのに使用できます。 Bing Entity Search の REST API はほとんどのプログラミング言語に対応していますが、このクライアントライブラリを使用すると、サービスをお使いのアプリケーションに簡単に統合することができます。このサンプルのソースコードは、GitHub にあります。

前提条件

Python 2.x または 3.x
Bing Entity Search SDK for Python

Python の仮想環境を使用することをお勧めします。仮想環境のインストールと初期化は、venv モジュールを使用して行えます。次にようにして、virtualenv をインストールできます。

python -m venv mytestenv

Bing Entity Search クライアントライブラリは、次のようにインストールします。

cd mytestenv
python -m pip install azure-cognitiveservices-search-entitysearch

Azure リソースを作成する

次のいずれかの Azure リソースを作成して、Bing Entity Search API の使用を開始します。

Bing Entity Search のリソース

ご自身でリソースを削除するまでは Azure portal からご利用いただけます。
Free 価格レベルを使ってサービスを試用し、後から運用環境用の有料レベルにアップグレードします。
Bing Entity Search は、Bing Search v7 リソースの有料レベルでも提供されています。

マルチサービスリソース

ご自身でリソースを削除するまでは Azure portal からご利用いただけます。
複数の Azure AI サービス全体で同じキーとエンドポイントをアプリケーションに使用します。

アプリケーションを作成して初期化する

お気に入りの IDE またはエディターで新しい Python ファイルを作成し、次の import ステートメントを追加します。

from azure.cognitiveservices.search.entitysearch import EntitySearchClient
from azure.cognitiveservices.search.entitysearch.models import Place, ErrorResponseException
from msrest.authentication import CognitiveServicesCredentials

対象のサブスクリプションキーとエンドポイントの変数を作成します。対象のキーを使用して新しい CognitiveServicesCredentials オブジェクトを作成して、クライアントをインスタンス化します。
```
subscription_key = "YOUR-SUBSCRIPTION-KEY"
endpoint = "YOUR-ENDPOINT"
client = EntitySearchclient(endpoint=endpoint, credentials=CognitiveServicesCredentials(subscription_key))
```

検索要求を送信して応答を受信する

client.entities.search() と検索クエリを使用して、Bing Entity Search に検索要求を送信します。
```
entity_data = client.entities.search(query="Gibralter")
```

エンティティが返された場合は、entity_data.entities.value をリストに変換して、最初の結果を表示します。

if entity_data.entities.value:

    main_entities = [entity for entity in entity_data.entities.value
                     if entity.entity_presentation_info.entity_scenario == "DominantEntity"]

    if main_entities:
        print(main_entities[0].description)

次のステップ

単一ページの Web アプリの作成

Bing Entity Search API とは

次の方法で共有

クイックスタート:Bing Entity Search クライアントライブラリを使用する

前提条件

Azure リソースを作成する

Bing Entity Search のリソース

マルチサービスリソース

アプリケーションを作成して初期化する

クライアントを作成して検索要求を送信する

エンティティの説明を取得して表示する

次のステップ

前提条件

Azure リソースを作成する

Bing Entity Search のリソース

マルチサービスリソース

プロジェクトの作成と初期化

検索クライアントを作成する

要求を送信して応答を受信する

次のステップ

前提条件

Azure リソースを作成する

Bing Entity Search のリソース

マルチサービスリソース

アプリケーションを作成して初期化する

要求を送信して応答を受信する

次のステップ

前提条件

Azure リソースを作成する

Bing Entity Search のリソース

マルチサービスリソース

アプリケーションを作成して初期化する

検索要求を送信して応答を受信する

次のステップ

その他のリソース

次の方法で共有

クイック スタート:Bing Entity Search クライアント ライブラリを使用する

前提条件

Azure リソースを作成する

アプリケーションを作成して初期化する

クライアントを作成して検索要求を送信する

エンティティの説明を取得して表示する

次のステップ

前提条件

Azure リソースを作成する

プロジェクトの作成と初期化

検索クライアントを作成する

要求を送信して応答を受信する

次のステップ

前提条件

Azure リソースを作成する

アプリケーションを作成して初期化する

要求を送信して応答を受信する

次のステップ

前提条件

Azure リソースを作成する

アプリケーションを作成して初期化する

検索要求を送信して応答を受信する

次のステップ

その他のリソース

クイックスタート:Bing Entity Search クライアントライブラリを使用する