Übersicht über Abfrageparameter

Wenn Sie einen System-API-Aufruf nur mit dem Endpunkt ausführen (wie in GET /activities), verfügen die Antwort-Nutzdaten über einen Standardsatz von Ressourcen und eine Standardstruktur.

Sie können die Antwort-Nutzdaten über das Standardverhalten hinaus durch folgende Maßnahmen verfeinern:

  • Festlegen eines benutzerdefinierten Eigenschaftensatzes
  • Herausfiltern von Ressourcen, die bestimmte Kriterien nicht erfüllen
  • Sortieren der Ressourcen
  • Begrenzen der Anzahl der Elemente, die in allen Nutzdaten zurückgegeben werden
  • Abrufen einer Anzahl der Gesamtressourcen in der Datenbank, die den Kriterien der Abfrage entsprechen

Sie können die Antwort-Nutzdaten mithilfe von Abfrageparametern verfeinern. Ein Abfrageparameter ist ein Ausdruck, welcher der HTTP-Anforderung hinzugefügt wird und die Standard-Antwort-Nutzdaten ändert.

Ein System-API-Aufruf kann eine beliebige Anzahl von Abfrageparametern enthalten. Die Liste der Abfrageparameter beginnt mit einem Fragezeichen (?). Wenn mehrere Abfrageparameter vorhanden sind, wird jeder durch ein kaufmännisches Und (&) getrennt. Zum Beispiel:

  • GET /activities?fields=*all
  • GET /activities?filter=escalated:eq:false
  • GET /activities?fields=*all&filter=escalated:eq:false

Eingeschlossene Ressourcen

Sie können den Abfrageparameter include verwenden, um Ressourcen einzuschließen, die mit den primären Ressourcen der Antwort verbunden sind. Sie können auch Abfrageparameter verwenden, um einen benutzerdefinierten Satz von Eigenschaften für eingeschlossene Ressourcen anzugeben, eingeschlossene Ressourcen herauszufiltern, die einem bestimmten Kriterium nicht entsprechen, die eingeschlossenen Ressourcen zu sortieren usw. Weitere Informationen finden Sie unter Verwenden von Abfrageparametern für eingeschlossene Ressourcen.

Anzeigen der Dokumentation von Abfrageparametern in der Swagger-Benutzeroberfläche

Für jeden Endpunkt stellt die Swagger-Benutzeroberfläche Beschreibungen der Abfrageparameter bereit, die von diesem Endpunkt unterstützt werden. Diese Informationen sind standardmäßig ausgeblendet. Um die Beschreibungen anzuzeigen, klicken Sie auf die Vorgangsschaltfläche des Endpunkts (z. B. die Schaltfläche GET für GET /activities). Die Beschreibungen der Abfrageparameter werden unter dem Endpunkt angezeigt.

Parameterdefinitionen

Im Abschnitt Parameters werden die einzelnen Abfrageparameter beschrieben.

Unterstützte Parameter

Der Abschnitt Responses enthält eine Registerkarte Model. Diese Registerkarte enthält Informationen zu den Feldern, die bestimmte Abfrageparameter unterstützen. Beispielsweise können Sie Ergebnisse für einige Felder sortieren, aber nicht für alle. Die Felder, die die Sortierung unterstützen, erscheinen im Modell mit dem Text "sortable": true.

Fehlermeldungen zu Abfrageparametern

Wenn Sie versuchen, einen Abfrageparameter für ein Feld zu verwenden, das diesen Parameter nicht unterstützt, gibt die System-API einen Fehler 400 Bad Request aufgrund einer fehlerhaften Anforderung und eine Fehlermeldung zurück. Wenn Sie beispielsweise Folgendes ausführen: GET /activities?sort=escalationDate stellt die System-API die folgende Fehlermeldung bereit:

"message": "The sort column 'escalationDate' is not a valid option. The valid 
      sort options are [assignedUser, dueDate, escalated, priority, status, subject], 
      optionally prefixed with '-' to indicate a descending sort."