Dataverse 検索クエリ

この例は、GitHub の SDK for .NET 検索操作のサンプル に由来します。 OutputSearchQuery 静的メソッドは、search パラメーターの値を受け入れます。

/// <summary>
/// Demonstrate query API
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance to use.</param>
/// <param name="searchTerm">The term to search for</param>
/// <returns></returns>
static void OutputSearchQuery(IOrganizationService service, string searchTerm)
{
    Console.WriteLine("OutputSearchQuery START\n");

    searchqueryRequest request = new() { 
        search = searchTerm,
        count = true,
        top = 7,
        entities = JsonConvert.SerializeObject(new List<SearchEntity>()
        {
            new SearchEntity()
            {
                Name = "account",
                SelectColumns = new List<string>() { "name", "createdon" },
                SearchColumns = new List<string>() { "name" },
                Filter = "statecode eq 0"
            },
            new SearchEntity()
            {
                Name = "contact",
                SelectColumns = new List<string>() { "fullname", "createdon" },
                SearchColumns = new List<string>() { "fullname" },
                Filter = "statecode eq 0"
            }
        }),
        orderby = JsonConvert.SerializeObject(new List<string>() { "createdon desc" }),
        filter = "createdon gt 2022-08-15"

    };
    
    var searchqueryResponse = (searchqueryResponse)service.Execute(request);

    var queryResults = JsonConvert.DeserializeObject<SearchQueryResults>(searchqueryResponse.response);
  

    Console.WriteLine($"\tCount:{queryResults.Count}");
    Console.WriteLine("\tValue:");
    queryResults.Value.ForEach(result =>
    {

        Console.WriteLine($"\t\tId:{result.Id}");
        Console.WriteLine($"\t\tEntityName:{result.EntityName}");
        Console.WriteLine($"\t\tObjectTypeCode:{result.ObjectTypeCode}");
        Console.WriteLine("\t\tAttributes:");
        foreach (string key in result.Attributes.Keys)
        {
            Console.WriteLine($"\t\t\t{key}:{result.Attributes[key]}");
        }
        Console.WriteLine("\t\tHighlights:");
        foreach (string key in result.Highlights.Keys)
        {
            Console.WriteLine($"\t\t\t{key}:");

            foreach (string value in result.Highlights[key])
            {
                Console.WriteLine($"\t\t\t\t{value}:");
            }
        }
        Console.WriteLine($"\t\tScore:{result.Score}\n");

    });
    Console.WriteLine("OutputSearchQuery END\n");
}

出力

OutputSearchQuery クラスの認証済みインスタンスで メソッドを呼び出し、searchTermを "Contoso" に設定する場合:

OutputSearchQuery(service: serviceClient, searchTerm: "Contoso");

出力は、次のようになります。

OutputSearchQuery START

        Count:1
        Value:
                Id:8b35eda1-ef69-ee11-9ae7-000d3a88a4a2
                EntityName:account
                ObjectTypeCode:0
                Attributes:
                        @search.objecttypecode:1
                        name:Contoso Pharmaceuticals (sample)
                        createdon:10/13/2023 5:41:21 PM
                        createdon@OData.Community.Display.V1.FormattedValue:10/13/2023 5:41 PM
                Highlights:
                        name:
                                {crmhit}Contoso{/crmhit} Pharmaceuticals (sample):
                Score:4.986711

OutputSearchQuery END

サポートするクラス

OutputSearchQuery メソッドは、次のサポートするクラスに基づいて要求を送信し、結果を処理します。

searchqueryRequest クラスおよび searchqueryResponse クラス

Power Platform CLI pac modelbuilder build コマンドを使用して、SDK for .NET 用の早期バインドクラスを生成するの説明に従ってこれらのクラスを生成します。

SearchEntity クラス

このクラスを使用して、 SearchEntity 型 データを作成します。

public sealed class SearchEntity
{
    /// <summary>
    /// Gets or sets the logical name of the table. Specifies scope of the query.
    /// </summary>
    [DataMember(Name = "name", IsRequired = true)]
    public string Name { get; set; }

    /// <summary>
    /// Gets or sets the list of columns that needs to be projected when table documents are returned in response. 
    /// If empty, only PrimaryName will be returned.
    /// </summary>
    [DataMember(Name = "selectcolumns")]
    public List<string> SelectColumns { get; set; }

    /// <summary>
    /// Gets or sets the list of columns to scope the query on.
    /// If empty, only PrimaryName will be searched on. 
    /// </summary>
    [DataMember(Name = "searchcolumns")]
    public List<string> SearchColumns { get; set; }

    /// <summary>
    /// Gets or sets the filters applied on the entity.
    /// </summary>
    [DataMember(Name = "filter")]
    public string Filter { get; set; }
}

SearchQueryResults クラス

このクラスを使用して、 searchqueryResponse.response 文字列プロパティから JSON データを逆シリアル化します。

public sealed class SearchQueryResults
{
    /// <summary>
    /// Provides error information from Azure Cognitive search.
    /// </summary>
    public ErrorDetail? Error { get; set; }

    /// <summary>
    /// A collection of matching records.
    /// </summary>
    public List<QueryResult>? Value { get; set; }

    /// <summary>
    /// If facets were requested in the query, a dictionary of facet values.
    /// </summary>
    public Dictionary<string, IList<FacetResult>>? Facets { get; set; }

    /// <summary>
    /// The query context returned as part of response. This property is used for backend search. It is included for future feature releases and is not currently used.
    /// </summary>
    public QueryContext? QueryContext { get; set; }

    /// <summary>
    /// If `"Count": true` is included in the body of the request, the count of all documents that match the search, ignoring top and skip.
    /// </summary>
    public long Count { get; set; }
}

ErrorDetail クラス

このクラスを使用して 、ErrorDetail データを逆シリアル化します。

public sealed class ErrorDetail
{
    /// <summary>
    /// Gets or sets the error code.
    /// </summary>
    [DataMember(Name = "code")]
    public string Code { get; set; }

    /// <summary>
    /// Gets or sets the error message.
    /// </summary>
    [DataMember(Name = "message")]
    public string Message { get; set; }

    /// <summary>
    /// Gets or sets additional error information.
    /// </summary>
    [DataMember(Name = "propertybag")]
    public Dictionary<string, object> PropertyBag { get; set; }
}

QueryResult クラス

このクラスを使用して QueryResult データを逆シリアル化します。

public sealed class QueryResult
{
    /// <summary>
    /// Gets or sets the identifier of the record
    /// </summary>
    public string Id { get; set; }

    /// <summary>
    /// Gets or sets the logical name of the table
    /// </summary>
    public string EntityName { get; set; }

    /// <summary>
    /// Gets or sets the object type code
    /// </summary>
    public int ObjectTypeCode { get; set; }

    /// <summary>
    /// Gets or sets the record attributes
    /// </summary>
    public Dictionary<string, object> Attributes { get; set; }

    /// <summary>
    /// Gets or sets the highlights
    /// </summary>
    public Dictionary<string, string[]> Highlights { get; set; }

    // Gets or sets the document score
    public double Score { get; set; }
}

FacetResult クラス

FacetResult データを逆シリアル化するには、このクラスを使用します。

public sealed class FacetResult
{
    /// <summary>
    /// Gets or sets the count of documents falling within the bucket described by this facet.
    /// </summary>
    [DataMember(Name = "count")]
    public long? Count { get; set; }

    /// <summary>
    /// Gets or sets value indicating the inclusive lower bound of the facet's range, or null to indicate that there is no lower bound.
    /// </summary>
    [DataMember(Name = "from")]
    public object From { get; set; }

    /// <summary>
    /// Gets or sets value indicating the exclusive upper bound of the facet's range, or null to indicate that there is no upper bound.
    /// </summary>
    [DataMember(Name = "to")]
    public object To { get; set; }

    /// <summary>
    /// Gets or sets type of the facet - Value or Range.
    /// </summary>
    [DataMember(Name = "type")]
    public FacetType Type { get; set; }

    /// <summary>
    /// Gets or sets value of the facet, or the inclusive lower bound if it's an interval facet.
    /// </summary>
    [DataMember(Name = "value")]
    public object Value { get; set; }

    /// <summary>
    /// Gets or sets additional/ Optional value of the facet, will be populated while faceting on lookups.
    /// </summary>
    [DataMember(Name = "optionalvalue")]
    public object OptionalValue { get; set; }
}

FacetType クラス

ファセット クエリ結果のタイプを指定します。

public enum FacetType
{
    /// <summary>
    /// The facet counts documents with a particular field value.
    /// </summary>
    [EnumMember(Value = "value")]
    Value = 0,

    /// <summary>
    /// The facet counts documents with a field value in a particular range.
    /// </summary>
    [EnumMember(Value = "range")]
    Range = 1,
}

QueryContext クラス

このクラスを使用して QueryContext データを逆シリアル化します。

public sealed class QueryContext
{
    /// <summary>
    /// Gets or sets the query string as specified in the request.
    /// </summary>
    [DataMember(Name = "originalquery")]
    public string OriginalQuery { get; set; }

    /// <summary>
    /// Gets or sets the query string that Dataverse search used to perform the query. 
    /// Dataverse search uses the altered query string if the original query string contained spelling mistakes or did not yield optimal results.
    /// </summary>
    [DataMember(Name = "alteredquery")]
    public string AlteredQuery { get; set; }

    /// <summary>
    /// Gets or sets the reason behind query alter decision by Dataverse search.
    /// </summary>
    [DataMember(Name = "reason")]
    public List<string> Reason { get; set; }

    /// <summary>
    /// Gets or sets the spell suggestion that are the likely words that represent user's intent. 
    /// This will be populated only when the query was altered by Dataverse search due to spell check.
    /// </summary>
    [DataMember(Name = "spellsuggestions")]
    public List<string> SpellSuggestions { get; set; }
}

searchquery アクションを使用して、searchqueryResponse 複合型を受け取ります。

これは、GitHub の Web API 検索操作のサンプルからの例です。

文字列の entities パラメーターに渡される、書式設定された JSON は、次のようになります。

[
  {
    "Name": "account",
    "SelectColumns": [
      "name",
      "createdon"
    ],
    "SearchColumns": [
      "name"
    ],
    "Filter": "statecode eq 0"
  },
  {
    "Name": "contact",
    "SelectColumns": [
      "fullname",
      "createdon"
    ],
    "SearchColumns": [
      "fullname"
    ],
    "Filter": "statecode eq 0"
  }
]

要求

POST [Organization Uri]/api/data/v9.2/searchquery
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 471

{
  "top": 7,
  "search": "Contoso",
  "skip": 0,
  "entities": "[{\"Name\":\"account\",\"SelectColumns\":[\"name\",\"createdon\"],\"SearchColumns\":[\"name\"],\"Filter\":\"statecode eq 0\"},{\"Name\":\"contact\",\"SelectColumns\":[\"fullname\",\"createdon\"],\"SearchColumns\":[\"fullname\"],\"Filter\":\"statecode eq 0\"}]",
  "orderby": "[\"createdon desc\"]",
  "filter": "createdon gt 2022-08-15",
  "count": true,
  "options": "null",
  "facets": "null"
}

応答

HTTP/1.1 200 OK
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.searchqueryResponse",
  "response": "{\"Error\":null,\"Value\":[{\"Id\":\"8b35eda1-ef69-ee11-9ae7-000d3a88a4a2\",\"EntityName\":\"account\",\"ObjectTypeCode\":0,\"Attributes\":{\"@search.objecttypecode\":1,\"name\":\"Contoso Pharmaceuticals (sample)\",\"createdon\":\"2023-10-13T17:41:21Z\",\"createdon@OData.Community.Display.V1.FormattedValue\":\"10/13/2023 5:41 PM\"},\"Highlights\":{\"name\":[\"{crmhit}Contoso{/crmhit} Pharmaceuticals (sample)\"]},\"Score\":4.95567}],\"Facets\":{},\"QueryContext\":null,\"Count\":1}"
}

文字列の response プロパティの書式設定された JSON 値は、次のようになります。

{
  "Error": null,
  "Value": [
    {
      "Id": "8b35eda1-ef69-ee11-9ae7-000d3a88a4a2",
      "EntityName": "account",
      "ObjectTypeCode": 0,
      "Attributes": {
        "@search.objecttypecode": 1,
        "name": "Contoso Pharmaceuticals (sample)",
        "createdon": "2023-10-13T17:41:21Z",
        "createdon@OData.Community.Display.V1.FormattedValue": "10/13/2023 5:41 PM"
      },
      "Highlights": {
        "name": [
          "{crmhit}Contoso{/crmhit} Pharmaceuticals (sample)"
        ]
      },
      "Score": 4.95567
    }
  ],
  "Facets": {},
  "QueryContext": null,
  "Count": 1
}

search/v2.0/query エンドポイントからの要求パラメーターと応答は、Web API と同じです。 URL が違うだけです。

要求 URL

POST [Organization Uri]/api/search/v2.0/query