Steuerung der Paginierung

GETs, die Sammlungen zurückgeben, geben in der Regel mehrere Stammressourcen zurück. Mit dem Parameter pageSize können Sie die Anzahl der Stammressourcen begrenzen, die in bestimmten Nutzdaten zurückgegeben werden. Dies kann nützlich sein, wenn eine Abfrage möglicherweise mehr Ressourcen zurückgibt als für die Leistung und Analyse praktisch ist. Verwenden Sie die folgende Syntax, um die Anzahl einzuschränken:

pageSize=n

wobei n die maximale Anzahl der pro Nutzdaten zurückzugebenden Ressourcen ist. Zum Beispiel:

GET /activities?pageSize=20

Jeder Ressourcentyp verfügt über eine standardmäßige pageSize. Dieser Wert wird verwendet, wenn in der Abfrage keine pageSize angegeben wird. Sie können eine pageSize angeben, die kleiner oder größer als die standardmäßige pageSize ist.

Außerdem hat jede Ressource eine maximale pageSize, und Sie können keine Abfrage ausführen, deren pageSize größer als der maximale Wert ist.

Beispiel: Angenommen, ein bestimmter Benutzer hat 125 Aktivitäten und die Aktivitätenressource hat eine standardmäßige pageSize von 25 und eine maximale pageSize von 100.

• GET /activities gibt die ersten 25 Aktivitäten zurück (unter Verwendung des Standardwerts für pageSize).
• GET /activities?pageSize=10 gibt die ersten 10 Aktivitäten zurück.
• GET /activities?pageSize=30 gibt die ersten 30 Aktivitäten zurück.
• GET /activities?pagesize=120 gibt einen Fehler zurück, weil der Wert für pageSize den Maximalwert für die Ressource übersteigt.

Die Werte pageSize für eine Ressource sind standardmäßig defaultPageSize=25 und maxPageSize=100. Einzelne Ressourcen können diese Werte in der API-Datei apiconfig.yaml überschreiben. (Beispielsweise überschreibt in claim-1.0apiconfig.yaml die Ressource ActivityPatterns die Standardwerte und verwendet defaultPageSize=100 und maxPageSize=500.)

Sie können die Abfrage pageSize auch für zugehörige Ressourcen verwenden, die über den Parameter include hinzugefügt werden. Weitere Informationen finden Sie unter Verwenden von Abfrageparametern für eingeschlossene Ressourcen.

Wenn Antwort-Nutzdaten eine Sammlung enthalten, wird jedes Element in der Sammlung im Abschnitt data der Nutzdaten aufgeführt. Für jedes Element gibt es einen Abschnitt links, der für dieses Element relevante Endpunkte enthält. Eine der Verknüpfungen ist self. Zum Beispiel:

{
    "attributes": {
        ...
        "id": "cc:32",
        ... },
        ...
    "links": {
        ...
        "self": {
            "href": "/common/v1/activities/cc:32",
            "methods": [
                "get",
                "patch"
            ]
        }
    }
}

Die Eigenschaft href der Verknüpfung self ist ein Endpunkt dieses spezifischen Elements. Bei Bedarf können Sie über diesen Link einen Aufruf erstellen, um auf dieses Element zu reagieren.

Wenn Antwort-Nutzdaten einige, aber nicht alle verfügbaren Ressourcen enthalten, enthalten die Nutzdaten auch einen Abschnitt mit Verknüpfungen auf Sammlungsebene im unteren Bereich. Diese Links stellen Operationen und Endpunkte bereit, mit denen Sie auf einer bestimmten "Seite" von Ressourcen agieren können. (In den folgenden Beschreibungen ist N die pageSize der Abfrage.)

• Die Verknüpfung first ist ein Endpunkt der ersten Elemente N.
  • Dies wird für alle Sammlungen angezeigt.
• Die Verknüpfung prev ist ein Endpunkt der Elemente N vor dem aktuellen Satz von Elementen.
  • Dies wird angezeigt, wenn Elemente vorhanden sind, die vor den Elementen in den Nutzdaten liegen.
• Die Verknüpfung next ist ein Endpunkt der Elemente N nach dem aktuellen Satz von Elementen.
  • Dies wird angezeigt, wenn Elemente vorhanden sind, die nach den Elementen in den Nutzdaten liegen.
• Die Verknüpfung self ist ein Endpunkt des aktuellen Satzes von Elementen.
  • Dies wird immer angezeigt (für Elemente und für Sammlungen).

Beispiel: Angenommen, dem aktuellen Sachbearbeiter sind 25 Aktivitäten zugewiesen. Die Antwort-Nutzdatenpakete haben eine pageSize von 5 und ein spezifisches Nutzdatenpaket hat den zweiten Aktivitätensatz (Aktivitäten 6 bis 10). Die Verknüpfungen auf Sammlungsebene für diese Nutzdaten wären:

"links": {
    "first": {
        "href": "/common/v1/activities?pageSize=5&fields=id",
        "methods": [
            "get"
        ]
    },
    "next": {
        "href": "/common/v1/activities?pageSize=5&fields=id&pageOffset=10",
        "methods": [
            "get"
        ]
    },
    "prev": {
        "href": "/common/v1/activities?pageSize=5&fields=id",
        "methods": [
            "get"
        ]
    },
    "self": {
        "href": "/common/v1/activities?pageSize=5&fields=id&pageOffset=5",
        "methods": [
            "get"
        ]
    }
}

Für den Zugriff auf eine Sammlung, die mit einer bestimmten Ressource beginnt, verwenden die System-APIs den Parameter pageOffset. Dieser Parameter wird in den Verknüpfungen prev und next für eine Sammlung verwendet. Der Index pageOffset beginnt mit 0, sodass ein theoretischer pageOffset=0 mit dem ersten Element beginnt und pageOffset=5 die ersten 5 Elemente überspringt und mit dem sechsten beginnt.

Es kann einige Schwierigkeiten geben, zu bestimmen, wie eine Verknüpfung mit dem richtigen Wert pageOffset erstellt wird. Daher empfiehlt Guidewire, dass Sie prev und next in den Antwort-Nutzdaten verwenden und vermeiden, eigene Abfragen pageOffset zu erstellen.

Bei der Datenabfrage können Sie die Gesamtanzahl der Ressourcen abrufen, die den Kriterien entsprechen. Verwenden Sie zum Abrufen dieser Nummer die folgende Syntax:

includeTotal=true

Wenn Sie diesen Abfrageparameter übermitteln, enthalten die Nutzdaten einen zusätzlichen Wert total, der die Summe angibt. Zum Beispiel:

"total": 72

Wenn der Abfrageparameter includeTotal verwendet wird, enthalten Antwort-Nutzdaten zwei Zählwerte:

• count - Die Anzahl der in diesen Nutzdaten zurückgegebenen Ressourcen.
• total - Die Gesamtanzahl der Ressourcen, die die Kriterien der Abfrage erfüllen.

Wenn die Gesamtzahl der Ressourcen, die die Kriterien erfüllen, kleiner oder gleich der pageSize ist, sind count und total gleich. Wenn die Gesamtanzahl der Ressourcen, die die Kriterien erfüllen, größer als pageSize ist, ist count geringer als die total. count kann niemals größer als total sein.

Aus Leistungsgründen zählt Guidewire die Gesamtzahl der Elemente nur bis zu 1000. Wenn total gleich 1000 ist, kann die tatsächliche Anzahl 1000 oder eine Zahl größer als 1000 sein.

In manchen Situationen ist es vielleicht interessant, nur die Gesamtanzahl der Ressourcen abzurufen, die bestimmte Kriterien erfüllen, ohne dass Informationen von einer bestimmten Ressource benötigt werden. Ein GET kann jedoch nicht nur eine eingeschlossene Summe zurückgeben. Wenn Ressourcen vorhanden sind, die die Kriterien erfüllen, muss der erste N-Satz von Ressourcen und mindestens ein Feld für jede Ressource zurückgegeben werden. Für Aufrufe, die gesendet werden, um nur die Gesamtzahl der Ressourcen abzurufen, empfiehlt Guidewire die Verwendung eines Aufrufs mit Abfrageparametern, die die kleinste Menge an Ressourceninformationen zurückgeben, z. B. GET ...?includeTotal=true&fields=id&pageSize=1.

Sie können die Abfrage includeTotal auch für zugehörige Ressourcen verwenden, die über den Parameter "include" hinzugefügt werden. Weitere Informationen finden Sie unter Verwenden von Abfrageparametern für eingeschlossene Ressourcen.

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.