Recherche Dataverse (héritée)

  • Article

Important

Cette documentation est destinée au point de terminaison de recherche Dataverse hérité. Nous vous recommandons d’utiliser le dernier point de terminaison de recherche Dataverse. Pour plus d’informations : Rechercher des enregistrements Dataverse

Pour commencer à utiliser la recherche Dataverse héritée (version 1.0), votre application émet une requête HTTP POST pour lancer une recherche Dataverse. Lors de la recherche de données, spécifiez des propriétés facultatives dans le corps de la requête pour définir les critères de recherche des données dans l’environnement.

La recherche Dataverse héritée comporte trois points de terminaison qui peuvent être utilisés dans Power Apps (make.powerapps.com) :

  • Recherche : /api/search/v1.0/query Fournit une page de résultats de recherche.

  • Suggestions : /api/search/v1.0/suggest Fournit des suggestions lorsque l’utilisateur saisit du texte dans un champ de formulaire.

  • Saisie semi-automatique : /api/search/v1.0/autocomplete Fournit la saisie semi-automatique de l’entrée lorsque l’utilisateur saisit du texte dans un champ de formulaire.

Les sections suivantes décrivent comment accéder aux fonctionnalités de recherche mentionnées ci-dessus à partir du code d’application.

La syntaxe minimale d’une requête HTTP de recherche Dataverse est comme ci-dessous.

POST [Organization URI]/api/search/v1.0/query
{  
  "search": "<search term>"
}

La valeur de la propriété search contient le terme à rechercher et a une limite de 100 caractères.

Une réponse de recherche réussie renvoie un statut HTTP de 200 et se compose de :

  • value : liste de tables. Par défaut, 50 résultats sont renvoyés. Cette propriété inclut également les points clés de la recherche, qui indiquent des correspondances avec la valeur de propriété search contenue dans la balise crmhit de la réponse.

  • totalrecordcount : nombre total de résultats (de type long). Une valeur de −1 est renvoyée si returntotalrecordcount est défini sur false (par défaut).

  • facets : les résultats de facette.

En outre, vous pouvez ajouter une ou plusieurs propriétés à la charge utile pour personnaliser la manière dont la recherche de suggestions doit être effectuée et les résultats renvoyés. Les propriétés prises en charge sont indiquées dans la section suivante.

Propriétés de la requête

Les propriétés suivantes sont prises en charge pour la recherche Dataverse à l’aide du point de terminaison de la requête.

entities:[list<string>] (facultatif)

La liste de tables par défaut recherche dans toutes les tables et colonnes configurées pour la recherche Dataverse. L’administrateur configure la liste par défaut lorsque la recherche Dataverse est activée.

facets:[list<string>] (facultatif)

Les facettes prennent en charge la capacité d’explorer les résultats des données après leur extraction.

POST [Organization URI]/api/search/v1.0/query
{  
  "search": "maria",

  "facets": ["@search.entityname,count:100",  
    "account.primarycontactid,count:100",  
    "ownerid,count:100",  
    "modifiedon,values:2019-04-27T00:00:00|2020-03-27T00:00:00|2020-04-20T00:00:00|2020-04-27T00:00:00",
    "createdon,values:2019-04-27T00:00:00|2020-03-27T00:00:00|2020-04-20T00:00:00|2020-04-27T00:00:00"]
}

filter:[string] (facultatif)

Les filtres sont appliqués lors de la recherche de données et sont spécifiés dans la syntaxe de type OData.

POST [Organization URI]/api/search/v1.0/query
{  
  "search": "maria",

  "filter": "account:modifiedon ge 2020-04-27T00:00:00,
    activities: regardingobjecttypecode eq 'account', annotation:objecttypecode eq 'account',
    incident: (prioritycode eq 1 or prioritycode eq 2)"
}

returntotalrecordcount: true | false (facultatif)

Indiquez true pour renvoyer le nombre total d’enregistrements ; sinon, false. La valeur par défaut est false.

skip:[int] (facultatif)

Spécifie le nombre de résultats de recherche à ignorer.

top:[int] (facultatif)

Spécifie le nombre de résultats de recherche à récupérer. La valeur par défaut est 50 et la valeur maximale est 100.

orderby:[list<string>] (facultatif)

Une liste de clauses séparées par des virgules où chaque clause se compose d’un nom de colonne suivi de « asc » (croissant, qui est la valeur par défaut) ou « desc » (décroissant). Cette liste spécifie comment classer les résultats par ordre de priorité. Par défaut, les résultats sont répertoriés par ordre décroissant de score de pertinence (@search.score). Pour les résultats avec des scores identiques, le classement sera aléatoire.

Pour un ensemble de résultats contenant plusieurs types de table, la liste des clauses pour orderby doit être globalement applicable (par exemple, modifiedon, createdon, @search.score). Notez que la spécification de la propriété orderby annule et remplace la valeur par défaut. Par exemple, pour classer les résultats (par ordre de priorité) par pertinence, suivis des enregistrements les plus récemment modifiés répertoriés le plus haut :

"orderby": ["@search.score desc", "modifiedon desc"]

Si la demande de requête inclut un filtre pour un type de table spécifique, orderby peut éventuellement spécifier des colonnes spécifiques à la table.

searchmode:any | all (facultatif)

Spécifie si any ou all (un ou tous les) termes de la recherche doivent être mis en correspondance pour que le document soit comptabilisé comme pertinent. La valeur par défaut est any.

Notes

La propriété searchMode dans un corps de requête de recherche contrôle si un terme avec l’opérateur NON est couplé avec l’opérateur ET ou OU avec d’autres termes dans la requête (en supposant qu’il n’y a pas d’opérateur + ou | sur les autres termes).

L’utilisation de "searchMode": "any" augmente le rappel des requêtes en incluant plus de résultats, et par défaut, sera interprété comme « OU NON ». Par exemple, « wifi-luxe » correspondra aux documents contenant le terme « wifi » ou à ceux qui ne contiennent pas le terme « luxe ».

L’utilisation de "searchMode": "all" augmente la précision des requêtes en incluant moins de résultats, et par défaut, sera interprété comme « ET NON ». Par exemple, « wifi-luxe » correspondra aux documents contenant le terme « wifi » et qui ne contiennent pas le terme « luxe ».

searchtype:simple | full (facultatif)

Le type de recherche spécifie la syntaxe d’une requête de recherche. L’utilisation de simple sélectionne la syntaxe de requête simple et full sélectionne la syntaxe de requête Lucene. La valeur par défaut est simple.

La syntaxe de requête simple prend en charge les fonctionnalités suivantes :

Fonctionnalité Description
Opérateurs booléens Opérateur ET ; désigné par +
Opérateur OU ; désigné par |
Opérateur NON ; désigné par -
Opérateurs de priorité Un terme de recherche « hôtel+(wifi | luxury) » recherchera les résultats contenant le terme « hôtel » et « wifi » ou « luxe » (ou les deux).
Caractères génériques Les caractères génériques de fin sont pris en charge. Par exemple, « Alp* » recherche « alpin ».
Concordances exactes Une requête entre guillemets " ".

La syntaxe de requête Lucene prend en charge les fonctionnalités suivantes :

Fonctionnalité Description
Opérateurs booléens Fournit un ensemble étendu par rapport à une syntaxe de requête simple.
Opérateur AND ; désigné par AND, +
Opérateur OU ; désigné par OR, ||
Opérateur NON ; désigné par NOT, !, –
Opérateurs de priorité La même fonctionnalité que pour la syntaxe de requête simple.
Caractères génériques En plus d’un caractère générique de fin, prend également en charge un caractère générique de début.
Caractère générique de fin - « alp* »
Caractère générique de début - “/.*pine/”
Recherche approximative Prend en charge les requêtes mal orthographiées jusqu’à 2 caractères.
"Uniersty~" vous renvoie à "University"
"Blue~1" renvoie à "glue", "blues"
Mise en avant des termes Pondère différemment certains termes d’une requête.
« Rock^2 électronique » renvoie des résultats où les concordances de « rock » sont plus importantes que celles de « électronique ».
Recherche par proximité Renvoie les résultats où les termes sont à moins de X mots les uns des autres, pour des résultats plus contextuels.
Par exemple, « hôtel aéroport »~5 renvoie les résultats où les mots « hôtel » et « aéroport » sont à moins de 5 mots l’un de l’autre, augmentant ainsi les chances de trouver un hôtel situé à proximité d’un aéroport.
Recherche par expression régulière (regex) Par exemple, /[mh]otel/ correspond à « motel » ou à « hotel ».

Notes

Les caractères génériques ne sont utilisés que pour l’exécution du mot dans la recherche Dataverse. En règle générale, l’interrogation avec un caractère générique de premier plan prendra beaucoup plus de temps que sans caractère générique, nous vous encourageons donc à explorer d’autres moyens de trouver ce que vous recherchez et à utiliser les caractères génériques principaux avec parcimonie, voire pas du tout.

Pour utiliser l’un des opérateurs de recherche dans le cadre du texte de recherche, échappez le caractère en le préfixant avec une seule barre oblique inverse (\). Les caractères spéciaux qui nécessitent un échappement sont les suivants : + - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

L’exemple suivant est une requête et une réponse d’une recherche de base.

Demande :

POST [Organization URI]/api/search/v1.0/query
{  
  "search": "maria",

  "facets": ["@search.entityname,count:100",  
    "account.primarycontactid,count:100",  
    "ownerid,count:100",  
    "modifiedon,values:2019-04-27T00:00:00|2020-03-27T00:00:00|2020-04-20T00:00:00|2020-04-27T00:00:00",
    "createdon,values:2019-04-27T00:00:00|2020-03-27T00:00:00|2020-04-20T00:00:00|2020-04-27T00:00:00"]
}

Réponse :

{
    "value": [
        {
            "@search.score": 0.4547767,
            "@search.highlights": {
                "emailaddress1": [
                    "{crmhit}maria{/crmhit}@contoso.com"
                ],
                "firstname": [
                    "{crmhit}Maria{/crmhit}"
                ],
                "fullname": [
                    "{crmhit}Maria{/crmhit} Sullivan"
                ]
            },
            "@search.entityname": "contact",
            "@search.objectid": "16ffc791-d06d-4d8c-84ad-89a8978e14f3",
            "ownerid": "bb2500d1-5e6d-4953-8389-bfedf57e3857",
            "owneridname": "Corey Gray",
            "@search.ownerid.logicalname": "systemuser",
            "@search.objecttypecode": 2,
            "fullname": "Maria Sullivan",
            "entityimage_url": **null**,
            "createdon": "10/9/2020 5:27 PM",
            "modifiedon": "10/9/2020 5:27 PM",
            "emailaddress1": "maria@contoso.com",
            "address1_city": **"Seattle"**,
            "address1_telephone1": **"206-400-0200"**,
            "parentcustomerid": **null**,
            "parentcustomeridname": **null**,
            "telephone1": **"206-400-0300"**
        }
    ],
    "facets": {
        "account.primarycontactid": [],
        "ownerid": [
            {
                "Type": "Value",
                "Value": "31ca7d4b-701c-4ea9-8714-a89a5172106e",
                "OptionalValue": "Corey Gray",
                "Count": 1
            }
        ],
        "@search.entityname": [
            {
                "Type": "Value",
                "Value": "contact",
                "Count": 1
            }
        ],
        "modifiedon": [
            {
                "Type": "Range",
                "To": "4/27/2019 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "4/27/2019 12:00 AM",
                "To": "3/27/2020 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "3/27/2020 12:00 AM",
                "To": "4/20/2020 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "4/20/2020 12:00 AM",
                "To": "4/27/2020 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "4/27/2020 12:00 AM",
                "Count": 1
            }
        ],
        "createdon": [
            {
                "Type": "Range",
                "To": "4/27/2019 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "4/27/2019 12:00 AM",
                "To": "3/27/2020 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "3/27/2020 12:00 AM",
                "To": "4/20/2020 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "4/20/2020 12:00 AM",
                "To": "4/27/2020 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "4/27/2020 12:00 AM",
                "Count": 1
            }
        ]
    },
    "totalrecordcount": -1
}

Suggestions

Les suggestions fournissent une liste de correspondances à la valeur de la propriété de recherche spécifiée, en fonction de la colonne principale d’un enregistrement de table. Ceci est différent d’une demande de recherche normale, car une recherche de suggestion ne recherche que dans la colonne principale d’un enregistrement, tandis que les demandes de recherche recherchent dans toutes les tables et colonnes activées pour la recherche Dataverse.

La syntaxe minimale d’une requête HTTP de recherche de suggestion est comme ci-dessous.

POST [Organization URI]/api/search/v1.0/suggest
{
  "search": "<text-fragment>"
}

La valeur de la propriété de recherche fournit une chaîne textuelle à rechercher et a une longueur minimale de trois caractères.

Une réponse de recherche réussie renvoie un statut HTTP de 200 et contient la « valeur », qui est une liste composée de texte ou un document où le texte est la suggestion avec des points clés et où le document est un dictionnaire <string,object> des résultats de suggestion. Par défaut, 5 résultats sont renvoyés. Les points clés de suggestion indiquent des correspondances avec la valeur de la propriété de recherche et sont contenus dans la balise crmhit de la réponse.

En outre, vous pouvez ajouter une ou plusieurs propriétés au corps de la requête pour personnaliser la manière dont la recherche de suggestions doit être effectuée et les résultats renvoyés. Les propriétés prises en charge sont indiquées dans la section suivante.

Propriétés des suggestions

usefuzzy:true | false (facultatif)

Utilisez la recherche approximative pour ne pas être embêté par les fautes d’orthographe. La valeur par défaut est false.

top:[int] (facultatif)

Nombre de suggestions à récupérer. La valeur par défaut est 5.

orderby:[List<string>] (facultatif)

Une liste de clauses séparées par des virgules où chaque clause se compose d’un nom de colonne suivi de asc (croissant) ou desc (décroissant). Cette liste spécifie comment classer les résultats par ordre de priorité. Par défaut, les résultats sont répertoriés par ordre décroissant de score de pertinence (@search.score). Pour les résultats avec des scores identiques, le classement sera aléatoire.

Pour un ensemble de résultats contenant plusieurs types de table, la liste des clauses pour orderby doit être globalement applicable (par exemple, modifiedon, createdon, @search.score). Notez que la spécification de la propriété orderby annule et remplace la valeur par défaut. Par exemple, pour classer les résultats (par ordre de priorité) par pertinence, suivis des enregistrements les plus récemment modifiés répertoriés le plus haut :

"orderby": ["@search.score desc", "modifiedon desc"]

Si la demande de requête inclut un filtre pour un type de table spécifique, orderby peut éventuellement spécifier des colonnes spécifiques à la table.

entities:[list<string>] (facultatif)

La valeur par défaut est la recherche dans toutes les tables configurées pour la recherche Dataverse.

filter:[string] (facultatif)

Les filtres sont appliqués lors de la recherche de données et sont spécifiés dans la syntaxe OData standard.

Demande :

POST [Organization URI]/api/search/v1.0/suggest
{  
  "search": "mar",

  "filter": "account:modifiedon ge 2020-04-27T00:00:00,
    activities:regardingobjecttypecode eq 'account', annotation:objecttypecode eq 'account'"
}

Vous trouverez ci-dessous un exemple de requête de recherche de suggestions.

Demande :

POST [Organization URI]/api/search/v1.0/suggest
{  
  "search": "mar"
}

Réponse :

{
    "value": [
        {
            "text": "{crmhit}Mar{/crmhit}ia Sullivan",
            "document": {
                "@search.objectid": "52a33850-8f0a-eb11-a813-000d3a8ab142",
                "@search.entityname": "contact",
                "@search.objecttypecode": 2,
                "fullname": "Maria Sullivan",
                "entityimage_url": **null**,
                "emailaddress1": "maria@contoso.com",
                "address1_city": **null**,
                "address1_telephone1": **null**,
                "parentcustomerid": **null**,
                "parentcustomeridname": **null**,
                "telephone1": **null**
            }
        }
    ]
}

Autocomplétion

Fournit la saisie semi-automatique des entrées utilisateur. La saisie semi-automatique est basée sur la colonne principale d’un enregistrement de table.

La syntaxe minimale d’une requête HTTP de recherche Dataverse est comme ci-dessous.

POST [Organization URI]/api/search/v1.0/autocomplete
{  
  "search": "<text-fragment>"
}

Une réponse de recherche réussie renvoie un statut HTTP de 200 et se compose de la « valeur », qui est une chaîne.

En outre, vous pouvez ajouter une ou plusieurs propriétés au corps de la requête pour personnaliser la manière dont la recherche de suggestions doit être effectuée et les résultats renvoyés. Les propriétés prises en charge sont indiquées dans la section suivante.

Propriétés de saisie semi-automatique

usefuzzy: true | false (facultatif)

La recherche approximative élimine les fautes d’orthographe. La valeur par défaut est false.

entities: [list<string>] (facultatif)

L’étendue par défaut recherche dans toutes les tables et colonnes configurées pour la recherche Dataverse.

filter: [string] (facultatif)

Les filtres sont appliqués lors de la recherche de données et sont spécifiés dans la syntaxe OData standard.

Demande :

POST [Organization URI]/api/search/v1.0/autocomplete
{  
  "search": "mar",

  "filter": "account:modifiedon ge 2020-04-27T00:00:00,
    activities:regardingobjecttypecode eq 'account', annotation:objecttypecode eq 'account'"
}

Vous trouverez ci-dessous un exemple de requête d’autocomplétion.

Demande :

POST [Organization URI]/api/search/v1.0/autocomplete
{  
  "search": "mar"
}

Réponse :

{
  "value": "{crmhit}maria{/crmhit}"
}

Voir aussi

Rechercher des enregistrements Dataverse
Requête de recherche Dataverse
Suggestion de recherche Dataverse
Recherche par exécution automatique Dataverse
Statistiques et statut de recherche Dataverse

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).