Zusammengesetzte Anforderungen

Im Anforderungsabschnitt werden nur POST, PATCH und DELETE unterstützt. Dazu gehören sowohl POSTs, die Daten erstellen, als auch POSTs, die Geschäftsaktionen ausführen (z. B. POST /assign).

Die Basissyntax für den Anforderungsabschnitt wird unten gezeigt.

{
  "requests": [
    {
      "method": "<post/patch/delete>",
      "uri": "<path>",
      "body": {
        "data": {
          "attributes": {
            "<field1>": "<value1>",
            "<field2>": "<value2>",
            ...
            }
        }
      }
    }, 
    {
      <next subrequest>
    },
    ...
    {
      <final subrequest>
    }
  ]
}

Die folgende einfache zusammengesetzte Anforderung erstellt beispielsweise zwei Notizen für die Aktivität xc:202.

POST <applicationURL>/rest/composite/v1/composite

{
  "requests": [   
    {
      "method": "post",
      "uri": "/common/v1/activities/xc:202/notes",
      "body": {
        "data": {
          "attributes": {
            "body": "Cloud API note #1."
          }
        }
      }
    },    
    {
      "method": "post",
      "uri": "/common/v1/activities/xc:202/notes",
      "body": {
        "data": {
          "attributes": {
            "body": "Cloud API note #2."
          }
        }
      }
    }
  ]
}

Die vollständige Syntax mit allen zusammengesetzten Anforderungsfunktionen finden Sie unter Vollständige Syntax für zusammengesetzte Anforderungen.

Informationen aus einer Unteranforderung können in späteren Unteranforderungen verwendet werden. Dies kann mithilfe zusammengesetzter Variablen erfolgen.

      "vars": [
        {
          "name": "newActivityId",
          "path": "$.data.attributes.id"
        }
      ]

${<varName>}

"uri": "/common/v1/activities/${newActivityId}/notes"

{
  "requests": [
    {
      "method": "post",
      "uri": "/claim/v1/claims/cc:34/activities",
      "body": {
        "data": {
          "attributes": {
              "activityPattern": "contact_insured",
              "subject": "Cloud API activity"
          }
        }
      },
      "vars": [
        {
          "name": "newActivityId",
          "path": "$.data.attributes.id"
        }
      ]
    },    
    {
      "method": "post",
      "uri": "/common/v1/activities/${newActivityId}/notes",
      "body": {
        "data": {
          "attributes": {
            "body": "Cloud API note #1."
          }
        }
      }
    }
  ]
}

Die Antwort auf eine zusammengesetzte Anforderung enthält einen Antwortbereich. Dieser Abschnitt enthält eine Unterantwort für jede Unteranforderung. Jede Unterantwort umfasst drei Abschnitte:

• Einen Abschnitt body, der standardmäßig die im entsprechenden Endpunkt definierten Standardantwortdaten enthält.
• Einen Abschnitt headers, der benutzerdefinierte Headers enthält.
• Ein Feld status, das den Statuscode der Teilantwort angibt.

Das Folgende ist beispielsweise der Antwortbereich und die erste Teilantwort für eine zusammengesetzte Anforderung, deren erste Teilanforderung eine Aktivität erstellt hat:

"responses": [
  {
    "body": {
      "data": {
        "attributes": {
          "activityPattern": "contact_insured",
          "activityType": {
            "code": "general",
            "name": "General"
            },
          "assignedByUser": {
            "displayName": "Andy Applegate",
            "id": "demo_sample:1",
            "type": "User",
            "uri": "/admin/v1/users/demo_sample:1"
          },
          ...
        },
        "checksum": "0",
        "links": {
          "assign": {
            "href": "/common/v1/activities/cc:403/assign",
            "methods": [
              "post"
            ]
          },
          ...
        }
      }
    },
    "headers": {
      "GW-Checksum": "0",
      "Location": "/common/v1/activities/xc:403"
    },
    "status": 201
  },

"includeResponse": false

{
  "requests": [   
    {
      "method": "post",
      "uri": "/common/v1/activities/xc:202/notes",
      "body": {
        "data": {
          "attributes": {
            "body": "Cloud API note #1."
          }
        }
      },
      "includeResponse": false
    },
    ...    

{
    "responseIncluded": false
},

{
  "requests": [
    {
      "method": "<post/patch>",
      "uri": "<path>",
      "body": {
        "data": {
          "attributes": {
            "<field1>": "<value1>",
            "<field2>": "<value2>",
            ...
            }
        }
      },
      "parameters" : {
        "fields" : "<value>"
      }
    }, 
    ...
  ]
}

{
  "requests": [
    {
      "method": "post",
      "uri": "/claim/v1/claims/cc:34/activities",
      "body": {
        "data": {
          "attributes": {
              "activityPattern": "contact_insured",
              "subject": "Cloud API activity"
          }
        }
      },
      "parameters" : {
        "fields" : "id,assignedUser"
      }
    },
  ...  

Der Abschnitt selections enthält Unterauswahlmöglichkeiten, die Daten abfragen. Diese werden nach der Unterauswahl im Anforderungsabschnitt ausgeführt und nur, wenn alle Unteranforderungen Daten erfolgreich übergeben.

Die Basissyntax für den Auswahlabschnitt wird unten gezeigt. Sie müssen nicht für jede Unterauswahl eine Methode angeben, da die einzige gültige Methode im Auswahlabschnitt GET ist.

  "selections": [
    {
      "uri": "<pathForFirstSubselection>"
    },
    {
      "uri": "<pathForSecondSubselection>"
    },
    ....
  ]

Beispiel: Der folgende Code erstellt eine neue Aktivität und eine Notiz für diese Aktivität. Anschließend wird die neu erstellte Aktivität abgefragt.

{
  "requests": [
    {
      "method": "post",
      "uri": "/claim/v1/claims/cc:34/activities",
      "body": {
        "data": {
          "attributes": {
              "activityPattern": "contact_insured",
              "subject": "Cloud API activity"
          }
        }
      },
      "vars": [
        {
          "name": "newActivityId",
          "path": "$.data.attributes.id"
        }
      ]
    },    
    {
      "method": "post",
      "uri": "/common/v1/activities/${newActivityId}/notes",
      "body": {
        "data": {
          "attributes": {
            "body": "Cloud API note #1."
          }
        }
      }
    }
  ],
  "selections": [
    {
      "uri": "/common/v1/activities/${newActivityId}
    }
  ]
}

Die vollständige Syntax mit allen zusammengesetzten Anforderungsfunktionen finden Sie unter Vollständige Syntax für zusammengesetzte Anforderungen.

  "selections": [
    {
      "uri": "<pathForFirstQuery>",
      "parameters" : {
        "fields" : "<value>",
        "filter" : [<value>],
        "includeTotal" : <value>,
        "pageOffset" : <value>,
        "pageSize" : <value>,
        "sort" : [<value>]
      }
    },
    ....
  ]

    {
      "uri": "/common/v1/activities",
      "parameters" : {
        "fields" : "assignedUser,dueDate,priority,subject"
      }

    {
      "uri": "/common/v1/activities",
      "parameters" : {
        "filter" : ["dueDate:gt:2022-12-20","status:in:open,complete"]      }

    {
      "uri": "/common/v1/activities",
      "parameters" : {
        "fields" : "assignedUser,dueDate,priority,subject",
        "filter" : ["dueDate:gt:2022-12-20","status:in:open,complete"],
        "includeTotal" : true,
        "pageSize" : 5,
        "sort" : ["dueDate"]
      }

Wenn eine der Unteranforderungen im Abschnitt requests fehlschlägt, führt die Cloud-API Folgendes aus:

• Übergibt keine der Daten
• Führt keine GETs im selections aus
• Gibt einen Fehler 400 zurück

Die Cloud-API gibt auch eine Antwort zurück.

• Die Antwort beginnt mit: "requestFailed": true. Dadurch wird es einfacher zu erkennen, dass die zusammengesetzte Anforderung keine Daten übergeben hat.
• Für die anfänglichen Unteranforderungen, die nicht fehlschlugen (sofern vorhanden), wird die Antwort zurückgegeben.
  • Dies ist entweder die vom zugehörigen Endpunkt (und allen Abfrageparametern) angegebene Antwort oder der Text "responseIncluded": false.
  • Die Standardantwort kann für Debugzwecke nützlich sein, da Sie den Status der Objekte sehen können, die vor der fehlgeschlagenen Unteranforderung erfolgreich waren.
• Für die fehlgeschlagene Unteranforderung wird die Fehlermeldung zurückgegeben.
• Für die Unteranforderungen nach der fehlgeschlagenen Unteranforderung wird der Text "skipped": true zurückgegeben.
• Wenn ein Abschnitt selections enthalten war, wird der Text "skipped": true für jede Unterauswahl zurückgegeben.

Das Folgende ist beispielsweise die Antwort für eine zusammengesetzte Anforderung mit fünf Unteranforderungen und einem Satz von Abfragen. Alle Unteranforderungen haben responseIncluded auf false gesetzt. Fehler bei der dritten Unteranforderung, weil das Attribut dueDate fälschlicherweise als dueDate geschrieben wurde.

{
  "requestFailed": true,
  "responses": [
    {
      "responseIncluded": false
    },
    {
      "responseIncluded": false
    },
    {
      "requestError": {
        "details": [
          {
            "message": "Schema definition 'ext.common.v1.common_ext-
                1.0#/definitions/Note' does not define any property
                named 'ueDate'",
            "properties": {
              "lineNumber": 1,
              "parameterLocation": "body",
              "parameterName": "body"
            }
          }
        ],
        "developerMessage": "The request parameters or body had issues. 
           See the details elements for exact details of the problems.",
        "errorCode": "gw.api.rest.exceptions.BadInputException",
        "status": 400,
        "userMessage": "The request parameters or body had issues"
      },
      "status": 400
    },
    {
      "skipped": true
    },
    {
      "skipped": true
    }
  ],
  "selections": [
    {
      "skipped": true
    }
  ]
}

Wenn nur im Abschnitt selections ein Fehler auftritt, werden die Unteranforderungen im Abschnitt requests ausgeführt, die Daten werden übergeben und die zusammengesetzte Anforderung wird mit einem Antwortcode 200 zurückgegeben, was den Erfolg anzeigt. Die Cloud-API versucht außerdem, jede Unterauswahl so gut wie möglich auszuführen.

Die Cloud-API protokolliert Informationen über zusammengesetzte Anforderungen sowohl auf der Ebene zusammengesetzter Anforderungen als auch auf der Ebene der Unteranforderung/Unterauswahl. Diese Informationen werden in den Protokollen unter dem Marker CompositeSubRequest angezeigt, der ein untergeordnetes Element des normalen Markers RestRequest ist.

Jede Unteranforderung und jede Unterauswahlprotokollnachricht enthält detaillierte Informationen für diese Unteranforderung/Unterauswahl, z. B. den tatsächlichen Pfad, die HTTP-Methode und die apiFqn. Sowohl für die Protokollierung der übergeordneten Anforderung als auch für die Unteranforderungsprotokollierung werden dieselben Protokollparameternamen und -konventionen verwendet, z. B. ob ein bestimmter Wert mit einer leeren Zeichenfolge protokolliert oder ausgelassen wird. Aber:

• Einige Parameter werden bei der Unteranforderung immer weggelassen, da sie nur für die übergeordnete Anforderung sinnvoll sind.
• Es werden einige zusätzliche zusammensetzungsspezifische Parameter hinzugefügt.

Beispiel: Angenommen, Sie haben die zuvor aufgeführte zusammengesetzte Anforderung ausgeführt, bei der eine zusammengesetzte Anforderung zwei Notizen für die Aktivität xc:202 erstellt. Die entsprechenden Protokolleinträge können wie folgt angezeigt werden. Beachten Sie, dass die erste Nachricht für die übergeordnete Anforderung und die nächsten beiden Nachrichten für die beiden Unteranforderungen bestimmt sind:

server-id-207          749bdc4c-34b9-4f63-9b54-d1b0442af2c5 2021-12-13 
14:40:30,803 INFO <RestService[ GW.PL ]> Operation started 
{path="/composite/v1/composite", from="[0:0:0:0:0:0:0:1]", method="POST", 
query="", startTime=1227026673066900, message="", eventType="START", 
serverID="server-id-207"}

server-id-207 aapplegate 749bdc4c-34b9-4f63-9b54-d1b0442af2c5 2021-12-13 
14:40:30,894 INFO <CompositeSubRequest[ RestRequest ]> Operation status 
{path="/common/v1/activities/xc:202/notes", query="", method="POST", 
pathTemplate="/activities/{activityId}/notes", 
apiFqn="ext.common.v1.common_ext-1.0", status=201, error="", userMessage="", 
devMessage="", elapsedTimeMs=53, message="Composite API subrequest 
succeeded", eventType="STATUS", serverID="server-id-207"}

server-id-207 aapplegate 749bdc4c-34b9-4f63-9b54-d1b0442af2c5 2021-12-13 
14:40:30,899 INFO <CompositeSubRequest[ RestRequest ]> Operation status 
{path="/common/v1/activities/xc:202/notes", query="", method="POST", 
pathTemplate="/activities/{activityId}/notes", 
apiFqn="ext.common.v1.common_ext-1.0", status=201, error="", userMessage="", 
devMessage="", elapsedTimeMs=4, message="Composite API subrequest 
succeeded", eventType="STATUS", serverID="server-id-207"}

Jede Unteranforderung oder Unterauswahl generiert immer eine Protokollanweisung, unabhängig davon, ob sie erfolgreich war, fehlgeschlagen ist oder aufgrund vorheriger Fehler übersprungen wurde. Eine separate Protokollanweisung wird auch speziell für die Übergabe der zusammengesetzten Anforderung hinzugefügt, unabhängig davon, ob die Übergabe erfolgreich war, fehlgeschlagen ist oder übersprungen wurde.

Zusammengesetzte Anforderungen haben die folgenden allgemeinen Einschränkungen:

• Die Anzahl der Unteranforderungen und Unterauswahlen in einer einzelnen zusammengesetzten Anforderung muss kleiner oder gleich dem Wert des Konfigurationsparameters MaximumAllowedNumberOfCompositeSubRequests sein. (In der Basiskonfiguration hat dieser Parameter den Wert 100.)
• Die Unteranforderungen können andere Endpunkte verwenden, die Teil der Cloud-API sind. Sie können jedoch keine Endpunkte außerhalb der Cloud-API verwenden, z. B. benutzerdefinierte Endpunkte, die von einem Versicherer erstellt wurden.
• Sie können keine Unteranforderung hinzufügen, die einen anderen Inhaltstyp als application/json verwendet.
  • Beispielsweise können Sie bei zusammengesetzten Anforderungen nicht mit Dokumentenressourcen arbeiten, da Dokumente mehrteilige Formulardaten verwenden.
• Es gibt keinen Mechanismus, um eine Reihe von Dingen zu durchlaufen.
  • Beispielsweise können Sie nicht mit einer Liste von Elementen beginnen und zugehörige Ressourcen für jedes Element in dieser Liste einschließen.

Es kann einige geschäftliche Anforderungen geben, bei denen Sie eine zusammengesetzte Anforderung verwenden müssen. Wenn Sie beispielsweise einen neuen Schadenfall mit einer unverifizierten Police erstellen, müssen Sie die Police und den Schadenfall in einer zusammengesetzten Anforderung erstellen.

Es gibt auch spezifische Geschäftsanforderungen, bei denen Sie keine zusammengesetzte Anforderung verwenden können. Zum Beispiel:

• Es ist nicht möglich, dass eine einzelne zusammengesetzte Anforderung für mehr als einen Schadenfall ausgeführt wird.
• Sie können die untergeordneten Objekte einer Serviceanfrage nicht erstellen oder aktualisieren.
• Für Serviceanfragen, die "Nur Angebot", "Angebot und Service" oder "Nur Service" sind, können Sie eine Serviceanfrage in einer einzigen zusammengesetzten Anforderung erstellen und übermitteln. Sie können diese Arten von Serviceanfragen jedoch nicht in derselben zusammengesetzten Anforderung in eine andere Phase ihres Lebenszyklus (z. B. in Bearbeitung, abgelehnt oder storniert) verschieben.
• In einer Composite-Anforderung können Sie keine Finanzobjekte erstellen oder ändern. Dazu gehören Reservesätze und Reservetransaktionen, Schecksätze und Zahlungstransaktionen sowie die Endpunkte des Schecklebenszyklus (z. B. POST /mark-issued). In einer Composite-Anforderung können Sie jedoch Informationen zu Finanzobjekten abrufen.

Viele der Beispiele in der vorherigen Liste beziehen sich auf Situationen, in denen eine zwischenzeitliche Datenübergabe erfolgen muss, was zusammengesetzte Anforderungen nicht zulassen. Die vorherige Liste soll jedoch nicht erschöpfend sein. Weitere Informationen zu Anforderungen oder Einschränkungen im Zusammenhang mit zusammengesetzte Anforderungen finden Sie im Abschnitt der Dokumentation, in dem die einzelnen Geschäftsanforderungen beschrieben werden.

Diese Dokumentation enthält Beispiele für Composite- Anforderungen für allgemeine Geschäftsaufgaben. Das beinhaltet:

• Erstellen eines neuen Schadenfalls mit einer unverifizierten Police: Beispiel für zusammengesetzte Schadenfall-Nutzdaten

Zusammengesetzte Anforderungen sind auf eine maximale Anzahl von Unteranforderungen und Unterauswahlen begrenzt. Das Maximum wird durch den Konfigurationsparameter MaximumAllowedNumberOfCompositeSubRequests angegeben. In der Basiskonfiguration hat dieser Parameter den Wert 100. Zusammengesetzte Anforderungen mit mehr als der maximalen Anzahl schlagen mit BadInputException fehl. (Der Höchstwert gilt für die Summe aus der Anzahl der Unteranfragen und der Anzahl der Unterauswahlen.)

Je größer die Anzahl der Unteranforderungen in einer zusammengesetzten Anforderung ist, desto größer ist die Wahrscheinlichkeit, dass es zu einem Leistungskompromiss kommt. Eine zusammengesetzte Anforderung mit der maximalen Anzahl von Unteranforderungen kann zu einer langsamen Antwort führen, je nachdem, wie hoch das Maximum ist und was diese Unteranforderungen tun.

In der Basiskonfiguration beträgt die maximale Anzahl der Unteranforderungen 100. Dieser kann auf einen höheren Wert angehoben werden. Zusammengesetzte Anforderungen mit einer erheblichen Anzahl von Unteranforderungen können jedoch negative Auswirkungen haben, z. B.:

• Die Anforderung beansprucht eine erhebliche Menge an Service-Ressourcen. Dies kann sowohl Speicher- als auch Datenbankressourcen umfassen.
• Die Anforderung dauert so lange, bis sie abgeschlossen ist, bis dem Anrufer eine Antwort zugestellt werden kann.

Daher empfiehlt Guidewire, die maximale Anzahl an Unteranforderungen auf den niedrigsten benötigten Wert zu setzen. Wenn ein berechtigtes geschäftliches Bedürfnis besteht, den Höchstwert über 100 anzuheben, empfiehlt Guidewire, das Limit nur so viel anzuheben, wie unbedingt erforderlich ist.

Beachten Sie außerdem, dass zusammengesetzte Anforderungen hinsichtlich der maximalen Größe eines Anforderungstextes Beschränkungen des Anwendungsservers unterliegen. Somit ist es möglich, dass eine zusammengesetzte Anforderung zu groß ist, um verarbeitet zu werden, selbst wenn die Anzahl der Unteranforderungen auf oder unter dem zulässigen Maximum liegt.

Im Folgenden finden Sie die vollständige Syntax für eine zusammengesetzte Anforderung:

{
  "requests": [
    {
      "method": "<post/patch/delete>",
      "uri": "<path>",
      "body": {
        "data": {
          "attributes": {
            "<field1>": "<value1>",
            "<field2>": "<value2>",
            ...
            }
        }
      },
      "parameters" : {
        "fields" : "<value>"
      },
      "vars": [
        {
          "name": "<name>",
          "path": "<path-starting-with-$>"
        },
        <next variable>,
        ...
      ],
      "includeResponse": false
    }, 
    {
      <next subrequest>
    },
    ...
    {
      <final subrequest>
    }
  ],
  "selections": [
    {
      "uri": "<pathForFirstQuery>",
      "parameters" : {
        "fields" : "<value>",
        "filter" : [<value>],
        "includeTotal" : <value>,
        "pageOffset" : <value>,
        "pageSize" : <value>,
        "sort" : [<value>]
      }
    },
    {
      <next subselection>
    },
    ...
    {
      <final subselection>
    }
  ]
}