範例：使用 Bing 實體搜尋 API 建立自訂技能

發行項
10/16/2024

在此範例中，了解如何建立 Web API 自訂技能。此技能會接受位置、公眾人物和組織，並傳回其描述。此範例會使用 Azure 函式來包裝 Bing 實體搜尋 API，以便其可以實作自訂的技能介面。

必要條件

如果您不熟悉自訂技能應實作的輸入/輸出介面，請閱讀自訂技能介面一文。
透過 Azure 入口網站建立 Bing 搜尋資源。有免費層可用，且對於此範例已夠用。
安裝 Visual Studio 或更新版本。

建立 Azure 函式

雖然這個範例使用 Azure Function 來裝載 Web API，但並非必要。只要您符合認知技能的介面需求，採取的方式並不重要。不過，Azure Functions 能讓您輕鬆建立自訂技能。

建立專案

在 Visual Studio 中，從 [檔案] 功能表中選取 [新增]>[專案]。
選擇 [Azure Functions] 作為範本，然後選取 [下一步]。輸入專案的名稱，然後選取 [建立]。函數應用程式名稱必須是有效的 C# 命名空間，因此不會使用底線、連字號或任何其他非英數字元。
選取具有長期支持的架構。
針對要新增至專案的函式類型，選擇 [HTTP 觸發程序]。
針對授權等級，選取 [函數]。
選取 [建立] 以建立函數專案和由 HTTP 觸發的函數。

新增程式碼以呼叫 Bing 實體 API

Visual Studio 會為所選函式類型建立具有重複使用程式碼的專案。方法上的 FunctionName 屬性會設定函式名稱。 HttpTrigger 屬性會指定由 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 實體搜尋 API 時取得的金鑰，在 key 常數中輸入您自己的金鑰值。

從 Visual Studio 測試函式

按 F5 以執行程式並測試函式行為。在此情況下，我們將使用下列函數來查閱兩個實體。使用 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 入口網站中，瀏覽至資源群組，並尋找您發佈的 EntitySearch 函數。在 [管理] 區段下，應該會看到主機金鑰。選取 [預設] 主機金鑰的 [複製] 圖示。

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

此範例所產生的結果，應該與您先前在本機環境中執行函數時看到的結果相同。

連線到您的管線

有了新的自訂技能之後，就可以將它加入您的技能集。下列範例示範如何呼叫技能，將描述新增至文件中的組織 (這可以延伸，以同時處理位置和人員)。將 [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 實體搜尋 API 建立自訂技能

必要條件

建立 Azure 函式

建立專案

新增程式碼以呼叫 Bing 實體 API

從 Visual Studio 測試函式

要求本文

回應

將函式發佈至 Azure

在 Azure 測試函式

要求本文

連線到您的管線

下一步

意見反應

其他資源