Requête de recherche Dataverse

Cet exemple est tiré de l’exemple du SDK pour les opérations de recherche .NET sur GitHub. La méthode statique OutputSearchQuery accepte une valeur pour le paramètre de recherche.

/// <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");
}

Sortie

Lorsque vous appelez la méthode OutputSearchQuery avec une instance authentifiée de la classe ServiceClient avec le searchTerm défini sur Contoso :

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

Le résultat ressemble à ce qui suit :

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

Classes de soutien

La méthode OutputSearchQuery dépend des classes de soutien suivantes pour envoyer la requête et traiter le résultat :

Classes searchqueryRequest et searchqueryResponse

Ces classes sont générées à l’aide de la commande de CLI Power Platform pac modelbuilder build comme décrit dans Générer des classes à liaison anticipée pour le SDK pour .NET.

Classe SearchEntity

Utilisée pour composer des données de type 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; }
}

Classe SearchQueryResults

À utiliser pour désérialiser les données JSON de la propriété de chaîne searchqueryResponse.response.

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; }
}

Classe ErrorDetail

Utilisée pour désérialiser les données 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; }
}

Classe QueryResult

Utilisée pour désérialiser les données 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; }
}

Classe FacetResult

Utilisée pour désérialiser les données 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; }
}

Classe FacetType

Spécifie le type de résultat d’une requête de facettes.

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,
}

Classe QueryContext

Utilisée pour désérialiser les données 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; }
}

Utilisez l’action searchquery pour recevoir un type complexe searchqueryResponse.

Cet exemple est tiré de l’exemple d’opérations de recherche d’API Web sur GitHub.

Le JSON formaté transmis au paramètre entities de chaîne ressemble à ceci :

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

Requête

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

Response

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

La valeur JSON formatée pour la propriété response de chaîne ressemble à ceci :

{
  "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
}

Les paramètres de requête et la réponse du point de terminaison search/v2.0/query sont les mêmes que ceux de l’API Web. Seule l’URL est différente.

URL requête

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