Verwenden von Abfrageparametern für eingeschlossene Ressourcen

Einige Endpunkte unterstützen die Möglichkeit, nach einem bestimmten Ressourcentyp und nach mit diesem Typ verbundenen Ressourcentypen zu suchen. Beispielsweise gibt der Endpunkt GET /activities standardmäßig nur Aktivitätsressourcen zurück. Sie können jedoch den include-Abfrageparameter verwenden, um Notizen, die mit den zurückgegebenen Aktivitäten verbunden sind, in die Antwort-Nutzdaten einzubeziehen. Diese Arten von Ressourcen werden als eingeschlossene Ressourcen bezeichnet. Die Technik des Hinzufügens von eingeschlossenen Ressourcen zu einem GET wird manchmal als Response-Einschluss oder Read-Einschluss bezeichnet.

Die Syntax für das Hinzufügen eingeschlossener Ressourcen lautet:

?include=<resourceName>

Beispiel: GET /activities?include=notes gibt alle dem aktuellen Aufrufer zugewiesenen Aktivitäten und alle mit diesen Aktivitäten verbundenen Notizen zurück.

Weitere Informationen zum Standardverhalten von include finden Sie unter Nutzdatenstruktur für eine Antwort mit eingeschlossenen Ressourcen.

Die meisten Abfrageparameter, die für primäre Ressourcen verwendet werden können, können auch für eingeschlossene Ressourcen verwendet werden.

Angeben von Abfrageparametern, die für eine eingeschlossene Ressource gelten

Das allgemeine Muster für Abfrageausdrücke in eingeschlossenen Ressourcen besteht darin, den Namen der eingeschlossenen Ressource irgendwo im Wert des Ausdrucks anzugeben. Der folgende Aufruf ruft beispielsweise alle Aktivitäten ab, die dem aktuellen Benutzer zugewiesen sind, sowie alle zugehörigen Notizen. Die Anzahl der zurückgegebenen Notizen ist auf 5 begrenzt.

GET /activities?include=notes&pageSize=notes:5

Eingeschlossene Ressourcen und primäre Ressourcen

Abfrageausdrücke für eingeschlossene Ressourcen sind unabhängig von Abfrageausdrücken für primäre Ressourcen. Es könnte ein Abfrageausdruck nur für primäre Ressourcen, nur für eingeschlossene Ressourcen oder für beide vorhanden sein. Die folgenden drei Abfragen geben beispielsweise alle Aktivitäten und die zugehörigen Notizen zurück. Die Auswirkungen des Parameters pageSize variieren jedoch.

  • GET /activities?pageSize=7&include=notes
    • Die Antwort ist auf 7 Aktivitäten begrenzt.
    • Für Notizen gibt es kein Limit.
  • GET /activities?include=notes&pageSize=notes:5
    • Es gibt keine Begrenzung für Aktivitäten.
    • Die Antwort ist auf 5 Notizen pro Aktivität begrenzt.
  • GET /activities?pageSize=7&include=notes&pageSize=notes:5
    • Die Antwort ist auf 7 Aktivitäten begrenzt.
    • Die Antwort ist auf 5 Notizen pro Aktivität begrenzt.

Eingeschlossene Ressourcen und andere eingeschlossene Ressourcen

Abfrageausdrücke für jede eingeschlossene Ressource sind auch unabhängig von Abfrageausdrücken für andere eingeschlossene Ressourcen. Wenn ein bestimmtes GET mehrere eingeschlossene Ressourcen enthält und Sie einen bestimmten Abfrageausdruck auf alle eingeschlossenen Ressourcen anwenden möchten, müssen Sie den Abfrageausdruck für jede eingeschlossene Ressource angeben.

Angenommen, Sie möchten alle Schadenfälle über GET abrufen. Sie möchten jedoch, dass die Antwort-Nutzdaten nur den Hauptkontakt und den Melder enthalten und dass für diese Kontakte nur die ID, das primäre Telefon und das Arbeitstelefon verwendet werden. Um diese Antwort zu erhalten, müssen Sie Folgendes senden:

GET /claims?include=mainContact,reporter
           &fields=mainContact,reporter
           &fields=mainContact:id,primaryPhone,workPhone
           &fields=reporter:id,primaryPhone,workPhone

Beachten Sie, dass in diesem Beispiel für jede eingeschlossene Ressource die Logik angegeben werden muss, die zurückgegebenen Felder auf nur id, primary phone und work phone zu beschränken.

Zusammenfassung der Abfrageparameter für eingeschlossene Ressourcen

Parameter filter

Sie können eingeschlossene Ressourcen herausfiltern, die ein bestimmtes Kriterium nicht erfüllen.

  • Syntax: filter=resource:field:op:value
  • Beispiel:
    GET claim/v1/claims/demo_sample:1?
       include=activities&
       filter=activities:escalated:eq:true
  • Rückgaben: Schadenfall demo_sample:1 und die zugehörigen eskalierten Aktivitäten

Parameter fields.

Sie können angeben, welche Felder in den eingeschlossenen Ressourcen zurückgegeben werden sollen.

  • Syntax: fields=resource:field_list
  • Beispiel: 
    GET claim/v1/claims/demo_sample:1?
          include=activities&
          fields=activities:id,dueDate
  • Rückgaben: Schadenfall demo_sample:1 und die darin enthaltenen Aktivitäten. Geben Sie für die Aktivitäten nur id und dueDate zurück.

Parameter sort

Sie können die eingeschlossenen Ressourcen sortieren. Diese Sortierung spiegelt sich sowohl in den Abschnitten related der Nutzdaten als auch im Abschnitt included wider.

  • Syntax: sort=resource:properties_list
  • Beispiel: 
    GET claim/v1/claims/demo_sample:1?
          include=activities&
          sort=activities:dueDate
  • Rückgaben: Schadenfall demo_sample:1 und die darin enthaltenen Aktivitäten, sortiert nach ihrem Fälligkeitsdatum.

Parameter pageSize

Sie können eine maximale Anzahl von eingeschlossenen Ressourcen pro Stammressource angeben. Wenn Sie pageSize für eingeschlossene Ressourcen verwenden, gibt es auf der eingeschlossenen Ressourcenebene auch keine Verknüpfungen prev und next.

  • Syntax: pageSize=resource:n
  • Beispiel: 
    GET claim/v1/claims/demo_sample:1?
          include=activities&
          pageSize=activities:5
  • Rückgaben: Schadenfall demo_sample:1 und bis zu 5 der enthaltenen Aktivitäten.

Parameter includeTotal

Sie können die Gesamtanzahl der eingeschlossenen Ressourcen angeben.

  • Syntax: includeTotal=resource:true
  • Beispiel: 
    GET claim/v1/claims/demo_sample:1?
          include=activities&
          includeTotal=activities:true
  • Rückgaben: Schadenfall demo_sample:1, die zugehörigen Aktivitäten und die Gesamtzahl der enthaltenen Aktivitäten für demo_sample:1.

Lernprogramm: GET mit Abfrageparametern für eingeschlossene Ressourcen senden

In diesem Lernprogramm wird davon ausgegangen, dass Sie Postman in Ihrer Umgebung mit dem korrekten Beispieldatensatz eingerichtet haben. Weitere Informationen finden Sie unter Lernprogramm: Einrichten Ihrer Postman-Umgebung.

Schritte des Lernprogramms

  1. Starten Sie in Postman eine neue Anforderung, indem Sie auf das + rechts neben der Registerkarte Launchpad klicken.
  2. Geben Sie als Basic Auth-Autorisierung den Benutzer aapplegate und das Kennwort gw an.
  3. Geben Sie den folgenden Aufruf ein und klicken Sie dann auf Senden:

    GET http://localhost:8080/cc/rest/common/v1/activities?included=notes

  4. Öffnen Sie eine zweite Anforderungsregisterkarte und geben Sie die Authorisierung Basic Auth mit dem Benutzer aapplegate und dem Kennwort gw an.
  5. Geben Sie den folgenden Aufruf ein und klicken Sie dann auf Senden:

    GET http://localhost:8080/cc/rest/common/v1/activities?included=notes&fields=id,subject&filter=notes:escalated

Überprüfen Ihrer Ergebnisse

Vergleichen Sie die beiden Nutzdaten. Beachten Sie die folgenden Unterschiede:

In den ersten Nutzdaten:

  • Für Aktivitäten werden die standardmäßigen Aktivitätenfelder zurückgegeben.
  • Für Notizen werden alle Notizen zurückgegeben.

Im zweiten Nutzdatenpaket:

  • Für Aktivitäten werden nur die Felder id und subject zurückgegeben.
  • Bei Notizen werden nur die eskalierten Notizen zurückgegeben.