例: Bing Entity Search API を使用してカスタムスキルを作成する

[アーティクル]
09/03/2024

この例では、Web API カスタムスキルを作成する方法について説明します。このスキルでは、場所、著名人、組織を受け入れ、それらの説明を返します。この例では、Azure Functionsを使用して、カスタムスキルインターフェイスを実装できるように Bing Entity Search API をラップします。

前提条件

カスタムスキルで実装する必要がある入出力インターフェイスがよくわからない場合は、カスタムスキルインターフェイスに関する記事を参照してください。
Azure portal から Bing 検索リソースを作成します。この例では、Free レベルを使用して十分です。
Visual Studio 以降をインストールします。

Azure Function の作成

この例では Azure 関数を使用して Web API をホストしていますが、必須ではありません。コグニティブスキルのインターフェイス要件を満たしていれば、どのような方法を使用してもかまいません。ただし、Azure Functions を使用すると、カスタムスキルを簡単に作成できます。

プロジェクトの作成

Visual Studio で、[ファイル] メニューから [新規]>[プロジェクト] の順に選択します。
テンプレートとして [Azure Functions] を選択し、[次へ] を選択します。プロジェクトの名前を入力し、[作成] を選択します。関数アプリ名は、C# 名前空間として有効である必要があります。そのため、アンダースコア、ハイフン、その他の英数字以外の文字は使用しないでください。
長期的なサポートを持つフレームワークを選択します。
プロジェクトに追加する関数の種類として [HTTP トリガー] を選択します。
権限レベルとして [機能] を選択します。
[作成] を選択して、関数プロジェクトと、HTTP でトリガーされる関数を作成します。

Bing Entity API を呼び出すコードを追加する

Visual Studio は、選択した関数型の定型コードを含むプロジェクトを作成します。メソッドの FunctionName 属性は、Functions の名前を設定します HttpTrigger 属性は、Functions が HTTP 要求によってトリガーされることを指定します。

Function1.cs のコンテンツを次のコードに置き換えます。

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;

namespace SampleSkills
{
    /// <summary>
    /// Sample custom skill that wraps the Bing entity search API to connect it with a 
    /// AI enrichment pipeline.
    /// </summary>
    public static class BingEntitySearch
    {
        #region Credentials
        // IMPORTANT: Make sure to enter your credential and to verify the API endpoint matches yours.
        static readonly string bingApiEndpoint = "https://api.bing.microsoft.com/v7.0/entities";
        static readonly string key = "<enter your api key here>";  
        #endregion

        #region Class used to deserialize the request
        private class InputRecord
        {
            public class InputRecordData
            {
                public string Name { get; set; }
            }

            public string RecordId { get; set; }
            public InputRecordData Data { get; set; }
        }

        private class WebApiRequest
        {
            public List<InputRecord> Values { get; set; }
        }
        #endregion

        #region Classes used to serialize the response

        private class OutputRecord
        {
            public class OutputRecordData
            {
                public string Name { get; set; } = "";
                public string Description { get; set; } = "";
                public string Source { get; set; } = "";
                public string SourceUrl { get; set; } = "";
                public string LicenseAttribution { get; set; } = "";
                public string LicenseUrl { get; set; } = "";
            }

            public class OutputRecordMessage
            {
                public string Message { get; set; }
            }

            public string RecordId { get; set; }
            public OutputRecordData Data { get; set; }
            public List<OutputRecordMessage> Errors { get; set; }
            public List<OutputRecordMessage> Warnings { get; set; }
        }

        private class WebApiResponse
        {
            public List<OutputRecord> Values { get; set; }
        }
        #endregion

        #region Classes used to interact with the Bing API
        private class BingResponse
        {
            public BingEntities Entities { get; set; }
        }
        private class BingEntities
        {
            public BingEntity[] Value { get; set; }
        }

        private class BingEntity
        {
            public class EntityPresentationinfo
            {
                public string[] EntityTypeHints { get; set; }
            }

            public class License
            {
                public string Url { get; set; }
            }

            public class ContractualRule
            {
                public string _type { get; set; }
                public License License { get; set; }
                public string LicenseNotice { get; set; }
                public string Text { get; set; }
                public string Url { get; set; }
            }

            public ContractualRule[] ContractualRules { get; set; }
            public string Description { get; set; }
            public string Name { get; set; }
            public EntityPresentationinfo EntityPresentationInfo { get; set; }
        }
        #endregion

        #region The Azure Function definition

        [FunctionName("EntitySearch")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequest req,
            ILogger log)
        {
            log.LogInformation("Entity Search function: C# HTTP trigger function processed a request.");

            var response = new WebApiResponse
            {
                Values = new List<OutputRecord>()
            };

            string requestBody = new StreamReader(req.Body).ReadToEnd();
            var data = JsonConvert.DeserializeObject<WebApiRequest>(requestBody);

            // Do some schema validation
            if (data == null)
            {
                return new BadRequestObjectResult("The request schema does not match expected schema.");
            }
            if (data.Values == null)
            {
                return new BadRequestObjectResult("The request schema does not match expected schema. Could not find values array.");
            }

            // Calculate the response for each value.
            foreach (var record in data.Values)
            {
                if (record == null || record.RecordId == null) continue;

                OutputRecord responseRecord = new OutputRecord
                {
                    RecordId = record.RecordId
                };

                try
                {
                    responseRecord.Data = GetEntityMetadata(record.Data.Name).Result;
                }
                catch (Exception e)
                {
                    // Something bad happened, log the issue.
                    var error = new OutputRecord.OutputRecordMessage
                    {
                        Message = e.Message
                    };

                    responseRecord.Errors = new List<OutputRecord.OutputRecordMessage>
                    {
                        error
                    };
                }
                finally
                {
                    response.Values.Add(responseRecord);
                }
            }

            return (ActionResult)new OkObjectResult(response);
        }

        #endregion

        #region Methods to call the Bing API
        /// <summary>
        /// Gets metadata for a particular entity based on its name using Bing Entity Search
        /// </summary>
        /// <param name="entityName">The name of the entity to extract data for.</param>
        /// <returns>Asynchronous task that returns entity data. </returns>
        private async static Task<OutputRecord.OutputRecordData> GetEntityMetadata(string entityName)
        {
            var uri = bingApiEndpoint + "?q=" + entityName + "&mkt=en-us&count=10&offset=0&safesearch=Moderate";
            var result = new OutputRecord.OutputRecordData();

            using (var client = new HttpClient())
            using (var request = new HttpRequestMessage {
                Method = HttpMethod.Get,
                RequestUri = new Uri(uri)
            })
            {
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);

                HttpResponseMessage response = await client.SendAsync(request);
                string responseBody = await response?.Content?.ReadAsStringAsync();

                BingResponse bingResult = JsonConvert.DeserializeObject<BingResponse>(responseBody);
                if (bingResult != null)
                {
                    // In addition to the list of entities that could match the name, for simplicity let's return information
                    // for the top match as additional metadata at the root object.
                    return AddTopEntityMetadata(bingResult.Entities?.Value);
                }
            }

            return result;
        }

        private static OutputRecord.OutputRecordData AddTopEntityMetadata(BingEntity[] entities)
        {
            if (entities != null)
            {
                foreach (BingEntity entity in entities.Where(
                    entity => entity?.EntityPresentationInfo?.EntityTypeHints != null
                        && (entity.EntityPresentationInfo.EntityTypeHints[0] == "Person"
                            || entity.EntityPresentationInfo.EntityTypeHints[0] == "Organization"
                            || entity.EntityPresentationInfo.EntityTypeHints[0] == "Location")
                        && !String.IsNullOrEmpty(entity.Description)))
                {
                    var rootObject = new OutputRecord.OutputRecordData
                    {
                        Description = entity.Description,
                        Name = entity.Name
                    };

                    if (entity.ContractualRules != null)
                    {
                        foreach (var rule in entity.ContractualRules)
                        {
                            switch (rule._type)
                            {
                                case "ContractualRules/LicenseAttribution":
                                    rootObject.LicenseAttribution = rule.LicenseNotice;
                                    rootObject.LicenseUrl = rule.License.Url;
                                    break;
                                case "ContractualRules/LinkAttribution":
                                    rootObject.Source = rule.Text;
                                    rootObject.SourceUrl = rule.Url;
                                    break;
                            }
                        }
                    }

                    return rootObject;
                }
            }

            return new OutputRecord.OutputRecordData();
        }
        #endregion
    }
}

Bing Entity Search API にサインアップしたときに取得したキーに基づいて、key 定数の独自の key 値を確実に入力します。

Visual Studio から Functions をテストする

F5 キーを押して、プログラムを実行し、関数の動作をテストします。ここでは、次の Functions を使用して、2 つのエンティティを検索します。 REST クライアントを使用して、次のような呼び出しを発行します。

POST https://localhost:7071/api/EntitySearch

要求本文

{
    "values": [
        {
            "recordId": "e1",
            "data":
            {
                "name":  "Pablo Picasso"
            }
        },
        {
            "recordId": "e2",
            "data":
            {
                "name":  "Microsoft"
            }
        }
    ]
}

回答

次の例のような応答が表示されます。

{
    "values": [
        {
            "recordId": "e1",
            "data": {
                "name": "Pablo Picasso",
                "description": "Pablo Ruiz Picasso was a Spanish painter [...]",
                "source": "Wikipedia",
                "sourceUrl": "http://en.wikipedia.org/wiki/Pablo_Picasso",
                "licenseAttribution": "Text under CC-BY-SA license",
                "licenseUrl": "http://creativecommons.org/licenses/by-sa/3.0/"
            },
            "errors": null,
            "warnings": null
        },
        "..."
    ]
}

Azure に関数を発行する

関数の動作に満足したら、発行できます。

ソリューションエクスプローラーで、プロジェクトを右クリックし、 [発行] を選択します。 [新規作成]>[発行] の順に選択します。
まだ Visual Studio を Azure アカウントに接続していない場合は、[アカウントの追加] を選択します。
画面の指示に従います。使用するアプリサービス、Azure サブスクリプション、リソースグループ、ホスティングプラン、ストレージアカウントに対して一意の名前を指定するように求められます。リソースグループ、ホスティングプラン、ストレージアカウントをまだ作成していない場合は新しく作成できます。終わったら、[作成] を選択します。
デプロイが完了したら、サイトの URL を書き留めておきます。これが Azure における関数アプリのアドレスになります。
Azure portal でリソースグループに移動し、発行した EntitySearch Functions を探します。 [管理] セクションに [ホストキー] が表示されます。 "既定" のホストキーの [コピー] アイコンを選択します。

Azure で関数をテストする

既定のホストキーが用意できたので、次のように関数をテストします。

POST https://[your-entity-search-app-name].azurewebsites.net/api/EntitySearch?code=[enter default host key here]

要求本文

{
    "values": [
        {
            "recordId": "e1",
            "data":
            {
                "name":  "Pablo Picasso"
            }
        },
        {
            "recordId": "e2",
            "data":
            {
                "name":  "Microsoft"
            }
        }
    ]
}

この例では、以前にローカル環境で Functions を実行したときと同じ結果が得られるはずです。

パイプラインに接続する

新しいカスタムスキルが作成できたので、スキルセットに追加できます。次の例では、スキルを呼び出して、ドキュメント内の組織に説明を追加する方法を示しています (これは場所および人の操作にも拡張できる可能性があります)。 [your-entity-search-app-name] をご自分のアプリの名前に置き換えます。

{
    "skills": [
      "[... your existing skills remain here]",  
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "description": "Our new Bing entity search custom skill",
        "uri": "https://[your-entity-search-app-name].azurewebsites.net/api/EntitySearch?code=[enter default host key here]",
          "context": "/document/merged_content/organizations/*",
          "inputs": [
            {
              "name": "name",
              "source": "/document/merged_content/organizations/*"
            }
          ],
          "outputs": [
            {
              "name": "description",
              "targetName": "description"
            }
          ]
      }
  ]
}

ここでは、組み込みのエンティティ認識スキルがスキルセットに存在すること、および組織のリストでエンリッチされたドキュメントがあることを想定しています。参考のため、必要なデータを生成するために十分なエンティティ抽出スキルの構成を示します。

{
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "name": "#1",
    "description": "Organization name extraction",
    "context": "/document/merged_content",
    "categories": [ "Organization" ],
    "defaultLanguageCode": "en",
    "inputs": [
        {
            "name": "text",
            "source": "/document/merged_content"
        },
        {
            "name": "languageCode",
            "source": "/document/language"
        }
    ],
    "outputs": [
        {
            "name": "organizations",
            "targetName": "organizations"
        }
    ]
},

次のステップ

お疲れさまでした。最初のカスタムスキルが作成されました。これで同じパターンに従って、独自のカスタム機能を追加できます。詳細については、以下のリンクをクリックしてください。

次の方法で共有

例: Bing Entity Search API を使用してカスタムスキルを作成する

前提条件

Azure Function の作成

プロジェクトの作成

Bing Entity API を呼び出すコードを追加する

Visual Studio から Functions をテストする

要求本文

回答

Azure に関数を発行する

Azure で関数をテストする

要求本文

パイプラインに接続する

次のステップ

フィードバック

その他のリソース

次の方法で共有

例: Bing Entity Search API を使用してカスタム スキルを作成する

前提条件

Azure Function の作成

プロジェクトの作成

Bing Entity API を呼び出すコードを追加する

Visual Studio から Functions をテストする

要求本文

回答

Azure に関数を発行する

Azure で関数をテストする

要求本文

パイプラインに接続する

次のステップ

フィードバック

その他のリソース

例: Bing Entity Search API を使用してカスタムスキルを作成する