Entitätsdatensätze abfragen

Abfragen von Entitätsdatensätzen.

API-Endpunkt

POST BaseURL/EntityService/<Entity>/query

• Verwenden Sie je nach Cloud-Plattform, die Sie verwenden, die zugehörige Basis-URL.

Anforderungsheader

Kopfzeile	Wert
Autorisierung	Inhaber <access_token>
Inhaltstyp	application/json

Hinweis:

Ersetzen Sie alle Werte zwischen den spitzen Klammern <...> durch die entsprechenden Anwendungsfallwerte.

Die <access_token> ist diejenige, die Sie erhalten haben, als Sie die externe Anwendung autorisiert haben. Es ist 1 Stunde lang verfügbar, dann müssen Sie ein neues generieren oder ein Aktualisierungstoken anfordern.

Abfrageparameter

Abfrageparameter	Datentyp	Beschreibung	Standardwert
ExpansionsLevel (Optional)	int32	Gibt die Tiefe der abzurufenden Bezugsdatensätze an. Der Wert dieses Parameters kann 1, 2 oder 3 sein.	2

Anforderungstext (erforderlich)

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

Anforderungstextschemas

Der Text der Endpunktanforderung query enthält die folgenden Komponenten:

selectedFields

Dies ist eine optionale Komponente vom Typ string. Sie gibt die Liste der Felder an, die für jeden Datensatz der Abfrage zurückgegeben werden sollen. Wenn sie leer bleibt oder die Abfrageliste leer ist, werden alle Datensatzfelder zurückgegeben. Der Standardwert ist null.

filterGroup

Dies ist eine erforderliche Komponente, mit der Sie die Filtereigenschaften für die Abfrage festlegen können. Es kombiniert die folgenden Eigenschaften:

• logischOperator – Dies ist eine optionale filterGroup- Eigenschaft vom Typ int32. Gibt an, ob alle Filter und Filtergruppen auf die Abfrage zutreffen. Verwenden Sie 0 , um alle Filter und Filtergruppen anzuwenden. Verwenden Sie 1 , um einen der Filter und Filtergruppen anzuwenden. Der Standardwert ist 0.

• abfrageFilter – Dies ist eine erforderliche filterGroup- Eigenschaft, die Ihnen bei der Definition des Filterausdrucks hilft. Es hat folgende Eigenschaften:

  queryFilter-Eigenschaft	Datentyp	Beschreibung
  fieldName	string	Gibt den Namen des Felds an, das gefiltert werden soll.
  operator	string	Gibt den Filteroperator an. Unterstützt Folgendes: contains, not contains, startswith, endswith, =, !=, >, <,>=, <=, in, not in. Verwenden Sie den entsprechenden Operator für den entsprechenden Feldtyp.
  Wert	string	Gibt den Filterwert an.

• filterGroups – Dies ist eine optionale filterGroup- Eigenschaft, für den Fall, dass Sie eine andere Filteroption für die Abfrage festlegen müssen. Sie enthält alle oben aufgeführten filterGroup- Eigenschaften.

Starten

Dies ist eine optionale Komponente vom Typ int32. Gibt die Anzahl der Datensätze an, die übersprungen werden sollen, bevor die Datensätze aus der Abfrage abgerufen werden. Kann zusammen mit der Eigenschaft „Grenzwert“ verwendet werden, um eine Paginierung zu implementieren. Die Datensätze sind aufsteigend nach ihren IDs sortiert. Um die Sortierreihenfolge zu ändern, verwenden Sie die Eigenschaft sortOptions . Der Standardwert ist 0.

limit

Dies ist eine optionale Komponente vom Typ int32. Gibt die maximale Anzahl von Datensätzen an, die aus der Entität gelesen werden sollen. Kann zusammen mit der Starteigenschaft verwendet werden, um eine Paginierung zu implementieren. Der Standardwert ist 100 und der Höchstwert ist 1000.

sortOptions

Dies ist eine optionale Komponente, mit der Sie die abgefragten Datensätze nach einer Liste von Feldern sortieren können. Wenn leer gelassen, werden die Datensätze aufsteigend nach ihren IDs sortiert. Es kombiniert die folgenden Eigenschaften:

• Feldname – Dies ist eine erforderliche SortierOptions- Eigenschaft vom Typ string. Gibt den Namen des Felds an, das zum Sortieren der Datensätze verwendet wird. Der Name muss einem gültigen Feld entsprechen, und es wird zwischen Groß- und Kleinschreibung unterschieden.
• isDescending – Dies ist eine optionale sortOptions- Eigenschaft vom Typ boolean. Legen Sie ihn auf true fest, wenn Sie die Datensätze absteigend sortieren möchten. Der Standardwert ist false.

Antworten

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

Schema des Antworttexts

Der Antworttext des Endpunkts query enthält die folgenden Komponenten:

• totalRecordCount - Die Gesamtzahl der Datensätze, die den angegebenen Abfragefiltern entsprechen.
• Wert – Ein Array von Entitätsdatensätzen, die den angegebenen Abfragefiltern entsprechen, begrenzt durch die Eigenschaft Grenzwert .

401 Nicht autorisiert

Sie sind nicht für den Zugriff auf Data Fabric/Data Service authentifiziert. Stellen Sie sicher, dass Ihr Assistant oder Roboter mit einem modernen Ordner in Ihrem Konto verbunden ist.

403 Forbidden

Sie haben keine Berechtigung zum Zugriff auf die Entität, das Feld oder den Datensatz, oder Sie verwenden einen nicht unterstützten Robotertyp. Wenden Sie sich an Ihren Administrator, um die erforderlichen Berechtigungen zu erhalten.

Aggregatfunktionen

Sie können aggregierte Berechnungen für eine einzelne Entität ausführen, indem Sie die Eigenschaften aggregates und groupBy zum Anforderungstext hinzufügen. Aggregate geben berechnete Werte (z. B. Gesamtwerte oder Durchschnittswerte) entweder eigenständig oder zusammen mit gruppierten Feldwerten zurück.

Anforderungstext

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

Aggregierte Anforderungskomponenten

Zusätzlich zu den Eigenschaften der Basisabfrage verwenden aggregierte Abfragen die folgenden Komponenten:

Aggregate

Dies ist eine optionale Komponente vom Typ Array. Gibt die anzuwendenden Aggregatfunktionen an. Sie können maximal 5 Aggregate pro Abfrage einschließen. Jedes Element hat die folgenden Eigenschaften:

Aggregate	Datentyp	Erforderlich	Beschreibung
function	string	Ja	Die anzuwendende Aggregatfunktion. Unterstützte Werte: COUNT, SUM, AVG, MIN, MAX. Groß-/Kleinschreibung wird nicht beachtet.
Feld	string	Ja	Das Feld, das aggregiert werden soll. Muss ein Feld der abgefragten Entität sein.
Alias	string	Nein	Der Name der Ergebnisspalte. Wenn er nicht angegeben wird, wird er automatisch als {FUNCTION}_{FIELD} generiert (z. B. COUNT_Id). Alias müssen innerhalb der Abfrage eindeutig sein (keine Unterscheidung zwischen Groß- und Kleinschreibung), mit einem Buchstaben beginnen und nur Buchstaben, Ziffern und Unterstriche enthalten.

Gruppieren nach

Dies ist eine optionale Komponente vom Typ Array von string. Gibt die Felder an, nach denen die Ergebnisse gruppiert werden sollen. Sie können maximal 5 Felder einschließen.

Wenn Sie sowohl aggregates als auch ein nicht leeres selectedFields angeben, ist groupBy erforderlich und jedes Feld in selectedFields muss auch in groupBy angezeigt werden.

Hinweis:

Legen Sie beim Sortieren einer aggregierten Abfrage sortOptions.fieldName auf ein aggregiertes alias oder auf ein Feld fest, das Teil von selectedFields/groupBy ist.

Unterstützung des Feldtyps

Function	Unterstützte Feldtypen
COUNT, MIN, MAX	Beliebiger Feldtyp, mit Ausnahme von Anhangsfeldern und mehrzeiligen Textfeldern (reguläres MULTILINE und großes MULTILINE_MAX).
SUM, ADF	Nur numerische Felder: INT, BIGINT, DECIMAL, FLOAT, REAL.

Limits und Einschränkungen

• Maximal 5 Aggregatfunktionen und 5 groupBy Felder pro Abfrage.
• Aggregate können nicht mit Erweiterungen (expansionLevel) kombiniert werden.
• Aggregate werden nur für Standardentitäten (tabellenbasiert) unterstützt. Sie werden nicht für virtuelle Entitäten (externe Datenquellen), Auswahlsätze oder Systementitäten unterstützt.
• Aggregate können nicht auf Anhangsfelder oder auf mehrzeilige Textfelder angewendet werden (sowohl reguläres MULTILINE als auch große MULTILINE_MAX). Dies gilt für jede Funktion, einschließlich COUNT.
• Berechtigungsfilter auf Datensatzebene (Zeilenebene) werden nicht auf aggregierte Ergebnisse angewendet: Aggregatwerte werden für alle Datensätze in der Entität berechnet, einschließlich Datensätze, die der Aufrufer nicht einzeln lesen kann. Leseberechtigungen auf Entitäts- und Feldebene werden weiterhin erzwungen; Sie können nicht nach einem Feld aggregieren oder gruppieren, zu dessen Lese Sie keine Berechtigung haben.

Beispiel: Anzahl nach einem Feld gruppiert

Zählt die Mitarbeiter pro Abteilung, absteigend nach Anzahl sortiert.

Anforderung:

POST BaseURL/EntityService/Employees/query

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

Antwort:

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

Abfragen mit mehreren Entitäten (Verknüpfungen)

Sie können Datensätze aus verwandten Entitäten in einer einzigen Abfrage kombinieren, indem Sie die Eigenschaft joins zum Anforderungstext hinzufügen. Verknüpfungen können eigenständig oder zusammen mit Aggregaten und groupBy verwendet werden.

Die Hauptentität (links) ist die in der Anforderungs-URL (<Entity>). Jede Verknüpfung fügt der Abfrage eine weitere Entität hinzu.

Anforderungstext

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

Feldqualifizierung

Wenn sich eine Abfrage über mehrere Entitäten erstreckt, beziehen Sie sich auf Felder als EntityName.fieldName. Sie können das unqualifizierte fieldName nur verwenden, wenn es für alle Entitäten in der Abfrage eindeutig ist; andernfalls wird sie als mehrdeutig abgelehnt. Bei Entitätsnamen wird die Groß-/Kleinschreibung nicht berücksichtigt.

Dies gilt für selectedFields, groupBy, sortOptions.fieldName, die filterGroup -Filter, aggregates.field und die Verknüpfungswerte on.left/on.right . In der Antwort werden Felder immer qualifiziert als EntityName.fieldName zurückgegeben.

Komponenten der Join-Anforderung

Verknüpfungen

Dies ist eine optionale Komponente vom Typ Array. Gibt die Entitäten an, die verbunden werden sollen. Sie können maximal 3 Verknüpfungen einschließen. Jedes Element hat die folgenden Eigenschaften:

haben	Datentyp	Erforderlich	Beschreibung
Typ	string	Ja	Der Join-Typ. Unterstützte Werte: INNER, LEFT. Groß-/Kleinschreibung wird nicht beachtet. Alle Verknüpfungen in einer einzelnen Abfrage müssen vom gleichen Typ sein; Das Kombinieren INNER und LEFT wird nicht unterstützt.
Entität	string	Ja	Der Name der Entität, die beitreten soll. Jede Entität kann nur einmal angezeigt werden und kann nicht die Hauptentität sein (Selbstverknüpfungen werden nicht unterstützt).
ein	object	Ja	Die Join-Bedingung. Enthält left und right.
auf.links	string	Ja	Das Verbindungsfeld auf der linken Seite, als fieldName (wenn eindeutig) oder EntityName.fieldName.
on.right	string	Ja	Das Verbindungsfeld auf der rechten Seite, als fieldName (wenn eindeutig) oder EntityName.fieldName.

Limits und Einschränkungen

• Maximal 3 Verknüpfungen pro Abfrage, alle vom gleichen Typ (INNER oder LEFT).
• Verbindungsschlüssel auf beiden Seiten müssen kompatible Typen haben (numerisch mit numerisch, Text mit Text, Datum mit Datum).
• Sie können nicht beitreten für: systemgenerierte Felder, verschlüsselte Felder, große (max. mehrzeilige) Textfelder, Auswahlsatz- oder Mehrfachauswahlsatzfelder oder Dateifelder (Anhang). Beziehungsfelder können als Verknüpfungsschlüssel verwendet werden.
• Die Klausel HAVING wird nicht unterstützt.
• Beim Kombinieren von Verknüpfungen mit Aggregaten gelten auch die im Abschnitt Aggregatfunktionen beschriebenen Aggregat- und groupBy -Regeln.

Beispiel: Linksverknüpfung mit einem Aggregat

Listet Kunden mit ihrer Bestellanzahl auf, einschließlich Kunden, die keine Bestellungen haben.

Anforderung:

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

Antwort:

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