Rechercher des enregistrements d’entités

Interroge les enregistrements d'entité.

Point de terminaison de l’API

POST BaseURL/EntityService/<Entity>/query

• Selon la plateforme Cloud que vous utilisez, utilisez l' URL de base associée.

En-têtes de requête.

En-tête	Valeur (Value)
Autorisation	Porteur <access_token>
Type de contenu	application/json

Remarque :

Remplacez toutes les valeurs entre les chevrons <...> par leurs valeurs de cas d’utilisation correspondantes.

Le <access_token> est celui que vous avez reçu lorsque vous avez autorisé l’application externe. Il est disponible pendant 1 heure, puis vous devez en générer un nouveau ou demander un jeton d'actualisation.

Paramètres de requête

Paramètre de requête	Type de données	Description	Valeur par défaut
NiveauExtension (facultatif)	int32	Spécifie la profondeur des enregistrements associés à récupérer. La valeur de ce paramètre peut être 1, 2 ou 3.	2

Corps de la requête (obligatoire)

{
  "selectedFields": [
    "string"
  ],
  "filterGroup": {
    "logicalOperator": 0,
    "queryFilters": [
      {
        "fieldName": "string",
        "operator": "string",
        "value": "string"
      }
    ],
    "filterGroups": [
    ]
  },
  "start": 0,
  "limit": 0,
  "sortOptions": [
    {
      "fieldName": "string",
      "isDescending": true
    }
  ]
}

Schémas du corps de la demande

Le corps de la demande de point de terminaison query comporte les composants suivants :

selectedFields

Il s'agit d'un composant facultatif, de type string. Il spécifie la liste des champs à renvoyer pour chaque enregistrement de la requête. Si elle est laissée vide, ou si la liste de requêtes est vide, tous les champs d'enregistrement sont renvoyés. La valeur par défaut est null.

Groupefiltre

Il s'agit d'un composant requis qui vous aide à définir les propriétés de filtrage de la requête. Il combine les propriétés suivantes :

• Opérateur logique - Il s'agit d'une propriété facultative filterGroup de type int32. Il spécifie si tous les filtres et groupes de filtres s'appliquent à la requête. Utilisez 0 pour appliquer tous les filtres et groupes de filtres. Utilisez 1 pour appliquer l'un des filtres et groupes de filtres. La valeur par défaut est 0.

• RequêteFiltre - Il s'agit d'une propriété FilterGroup requise qui vous aide à définir l'expression de filtrage. Il possède les propriétés suivantes:

  PropriétéQueryFilter	Type de données	Description
  fieldName	string	Spécifie le nom du champ à filtrer.
  operator	string	Spécifie l'opérateur de filtre. Prend en charge les éléments suivants: contains, not contains, startswith, endswith, =, !=, >, <,>=, <=, in, not in. Utilisez l'opérateur adéquat pour le type de champ correspondant.
  valeur	string	Spécifie la valeur de filtrage.

• filterGroups : il s'agit d'une propriété facultative filterGroup , au cas où vous devriez définir une autre option de filtrage sur la requête. Il contient toutes les propriétés FilterGroup répertoriées ci-dessus.

Démarrer (Start)

Il s'agit d'un composant facultatif, de type int32. Spécifie le nombre d’enregistrements à ignorer avant de récupérer les enregistrements de la requête. Peut être utilisé avec la propriété limite pour implémenter la pagination. Les enregistrements sont triés par ordre croissant par leurs ID. Pour modifier l'ordre de tri, utilisez la propriété triOptions . La valeur par défaut est 0.

limit

Il s'agit d'un composant facultatif, de type int32. Spécifie le nombre maximal d’enregistrements à lire à partir de l’entité. Peut être utilisé avec la propriété de début pour implémenter la pagination. La valeur par défaut est 100 et la valeur maximale est 1000.

sortOptions

Il s'agit d'un composant facultatif qui vous aide à trier les enregistrements interrogés en fonction d'une liste de champs. Si ce champ est laissé vide, les enregistrements sont triés par ordre croissant d'ID. Il combine les propriétés suivantes :

• FieldName : il s'agit d'une propriété SortOptions requise, de type string. Spécifie le nom du champ utilisé pour trier les enregistrements. Le nom doit correspondre à un champ valide et est sensible à la casse.
• EstDécroissant : il s'agit d'une propriété SortOptions facultative, de type boolean. Définissez ce paramètre sur true si vous souhaitez trier les enregistrements par ordre décroissant. La valeur par défaut est false.

Réponses

200 OK

{
  "TotalRecordCount": 0,
  "Value": [
    {
      "ClosingDate": "2021-03-04",
      "CreatedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "CreateTime": "2021-03-04T10:21:22.771Z",
      "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "Logo": {
        "Name": "string",
        "Path": "string",
        "Size": 0,
        "Type": "string"
      },
      "Name": "string",
      "Nations": 0,
      "OlymipcsVersion": 0,
      "OpeningDate": "2021-03-04",
      "UpdatedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "UpdateTime": "2021-03-04T10:21:22.771Z"
    }
  ]
}

Schéma du corps de la réponse

Le corps de la réponse du point de terminaison query comporte les composants suivants :

• totalRecordCount : le nombre total d'enregistrements correspondant aux filtres de requête spécifiés.
• value : Tableau d'enregistrements d'entités correspondant aux filtres de requête spécifiés, limité par propriété limit .

401 Non autorisé

Votre authentification ne vous permet pas d’accéder à Data Fabric/Data Service. Assurez-vous que votre Assistant ou votre robot est connecté à un dossier moderne de votre compte.

403 Forbidden

Vous n’êtes pas autorisé à accéder à l’entité, au champ, ni à l’enregistrement, ou utilisez un type de robot non pris en charge. Contactez votre administrateur afin d’obtenir les autorisations requises.

Fonctions agrégées

Vous pouvez effectuer des calculs agrégés sur une seule entité en ajoutant les propriétés aggregates et groupBy au corps de la requête. Les agrégats renvoient des valeurs calculées (telles que des totaux ou des moyennes), sur leur propre ou avec des valeurs de champ regroupées.

Corps de la requête

{
  "selectedFields": [
    "Department"
  ],
  "aggregates": [
    {
      "function": "COUNT",
      "field": "Id",
      "alias": "EmployeeCount"
    }
  ],
  "groupBy": [
    "Department"
  ],
  "filterGroup": {
    "logicalOperator": 0,
    "queryFilters": [
      {
        "fieldName": "Status",
        "operator": "=",
        "value": "Active"
      }
    ]
  },
  "sortOptions": [
    {
      "fieldName": "EmployeeCount",
      "isDescending": true
    }
  ],
  "start": 0,
  "limit": 100
}

Agréger les composants de la demande

Outre les propriétés des requêtes de base, les requêtes agrégées utilisent les composants suivants:

Agrégations

Il s'agit d'un composant facultatif, de type tableau. Elle spécifie les fonctions agrégées à appliquer. Vous pouvez inclure un maximum de 5 agrégats par requête. Chaque élément possède les propriétés suivantes:

propriété d'agrégations	Type de données	Requis	Description
function	string	Oui (Yes)	La fonction d’agrégation à appliquer. Valeurs prises en charge: COUNT, SUM, AVG, MIN, MAX. Insensible à la casse.
Champ	string	Oui (Yes)	Le champ à agréger. Doit être un champ de l’entité interrogée.
Alias	string	Non (No)	Le nom de la colonne de résultat. S'il est omis, il est généré automatiquement sous la forme {FUNCTION}_{FIELD} (par exemple, COUNT_Id). Les alias doivent être uniques dans la requête (insensibles à la casse), commencer par une lettre et contenir uniquement des lettres, des chiffres et des traits de soulignement.

Regrouper par

Il s'agit d'un composant facultatif, de type tableau de string. Il spécifie les champs par lesquels regrouper les résultats. Vous pouvez inclure un maximum de 5 champs.

Lorsque vous indiquez à la fois aggregates et un selectedFields non vide, groupBy est requis, et chaque champ de selectedFields doit également apparaître dans groupBy.

Remarque :

Lors du tri d'une requête agrégée, définissez sortOptions.fieldName sur un alias agrégé ou sur un champ qui fait partie de selectedFields/groupBy.

Prise en charge des types de champs

Function	Types de champs pris en charge
DÉCOMPTE, MN, MAX	Tous les types de champs, à l'exception des champs de pièce jointe et des champs de texte multiligne ( MULTILINE régulier et MULTILINE_MAX volumineux).
SOMME, MGA	Champs numériques uniquement: INT, BIGINT, DECIMAL, FLOAT, REAL.

Limites et restrictions

• Un maximum de 5 fonctions agrégées et 5 groupBy champs par requête.
• Les agrégats ne peuvent pas être combinés avec des développements (expansionLevel).
• Les agrégats sont pris en charge sur les entités standard (basées sur une table) uniquement. Elles ne sont pas prises en charge par rapport aux entités virtuelles (sources de données externes), aux ensembles de choix ou aux entités système.
• Les agrégats ne peuvent pas être appliqués aux champs de pièce jointe ou aux champs de texte multiligne (à la fois MULTILINE régulier et MULTILINE_MAX volumineux). Cela s'applique à toutes les fonctions, y compris COUNT.
• Les filtres d'autorisation au niveau de l'enregistrement ne sont pas appliqués aux résultats agrégés: les valeurs agrégées sont calculées sur tous les enregistrements de l'entité, y compris les enregistrements que l'appelant ne peut pas lire individuellement. Les autorisations de lecture au niveau de l’entité et du champ sont toujours appliquées. vous ne pouvez pas agréger ou regrouper par un champ que vous n'avez pas l'autorisation de lire.

Exemple: décompte regroupé par un champ

Compte les employés par service, triés par nombre décroissant.

Requête :

POST BaseURL/EntityService/Employees/query

{
  "selectedFields": ["Department"],
  "aggregates": [
    { "function": "COUNT", "field": "Id", "alias": "EmployeeCount" }
  ],
  "groupBy": ["Department"],
  "sortOptions": [
    { "fieldName": "EmployeeCount", "isDescending": true }
  ]
}

Réponse :

{
  "TotalRecordCount": 3,
  "Value": [
    { "Department": "Engineering", "EmployeeCount": 150 },
    { "Department": "Sales", "EmployeeCount": 80 },
    { "Department": "HR", "EmployeeCount": 20 }
  ]
}

Requêtes multi-entités

Vous pouvez combiner des enregistrements d'entités connexes dans une seule requête en ajoutant la propriété joins au corps de la requête. Les jointures peuvent être utilisées seules ou avec des agrégats et groupBy.

L'entité principale (de gauche) est celle de l'URL de la requête (<Entity>). Chaque jointure ajoute une autre entité à la requête.

Corps de la requête

{
  "selectedFields": [
    "Employees.Name",
    "Departments.Name"
  ],
  "joins": [
    {
      "type": "INNER",
      "entity": "Departments",
      "on": {
        "left": "Employees.DepartmentId",
        "right": "Departments.Id"
      }
    }
  ],
  "sortOptions": [
    {
      "fieldName": "Employees.Name",
      "isDescending": false
    }
  ],
  "start": 0,
  "limit": 100
}

Qualification de champ

Lorsqu'une requête couvre plusieurs entités, faites référence aux champs comme EntityName.fieldName. Vous pouvez utiliser l' fieldName non qualifié uniquement lorsqu'il est unique dans toutes les entités de la requête; dans le cas contraire, elle est rejetée comme ambiguë. Les noms d'entité ne sont pas sensibles à la casse.

Cela s'applique aux valeurs selectedFields, groupBy, sortOptions.fieldName, aux filtres filterGroup , aggregates.field et aux valeurs de jointure on.left/on.right . Dans la réponse, les champs sont toujours renvoyés qualifié comme EntityName.fieldName.

Composants de la demande d'adhésion

Rejoint

Il s'agit d'un composant facultatif, de type tableau. Spécifie les entités à joindre. Vous pouvez inclure un maximum de 3 jointures. Chaque élément possède les propriétés suivantes:

rejoint la propriété	Type de données	Requis	Description
Type	string	Oui (Yes)	Le type de jointure. Valeurs prises en charge: INNER, LEFT. Insensible à la casse. Toutes les jointures au sein d’une même requête doivent être du même type. la combinaison INNER et LEFT n'est pas prise en charge.
Entité	string	Oui (Yes)	Le nom de l'entité à rejoindre. Chaque entité ne peut s'afficher qu'une seule fois et ne peut pas être l'entité principale (les jointures automatiques ne sont pas prises en charge).
activé	object	Oui (Yes)	La condition de jointure. Contient left et right.
sur.gauche	string	Oui (Yes)	Le champ de jointure sur le côté gauche, sous la forme fieldName (si sans ambiguïté) ou EntityName.fieldName.
à droite	string	Oui (Yes)	Le champ de jointure sur le côté droit, sous la forme fieldName (si sans ambiguïté) ou EntityName.fieldName.

Limites et restrictions

• Un maximum de 3 jointures par requête, toutes du même type (INNER ou LEFT).
• Les clés de jointure des deux côtés doivent avoir des types compatibles (numérique avec numérique, texte avec texte, date avec date).
• Vous ne pouvez pas vous inscrire sur: champs générés par le système, champs chiffrés, champs de texte volumineux (multilignes max.), ensemble de choix ou champs à ensembles de choix multiples ou champs de fichier (pièce jointe). Les champs de relation peuvent être utilisés comme clés de jointure.
• La clause HAVING n'est pas prise en charge.
• Lors de la combinaison de jointures avec des agrégats, les règles d'agrégation et groupBy décrites dans la section Fonctions d'agrégation s'appliquent également.

Exemple: jointure à gauche avec une agrégation

Répertorie les clients avec leur nombre de commandes, y compris les clients qui n'ont pas de commandes.

Requête :

POST BaseURL/EntityService/Customers/query

{
  "selectedFields": ["Customers.Id", "Customers.Name"],
  "aggregates": [
    { "function": "COUNT", "field": "Orders.Id", "alias": "OrderCount" }
  ],
  "joins": [
    {
      "type": "LEFT",
      "entity": "Orders",
      "on": { "left": "Customers.Id", "right": "Orders.CustomerId" }
    }
  ],
  "groupBy": ["Customers.Id", "Customers.Name"],
  "sortOptions": [
    { "fieldName": "OrderCount", "isDescending": true }
  ]
}

Réponse :

{
  "TotalRecordCount": 3,
  "Value": [
    { "Customers.Id": "C-001", "Customers.Name": "Acme Corp", "OrderCount": 12 },
    { "Customers.Id": "C-002", "Customers.Name": "Globex", "OrderCount": 3 },
    { "Customers.Id": "C-003", "Customers.Name": "Initech", "OrderCount": 0 }
  ]
}