API-Antwortfilter

Revised: 26 August 2020

Funktionsübersicht

API-Antwortfilter, auch bekannt als Filter oder API-Filter, vereinfachen die Antwortausgabe und verbessern die Leistung drastisch. Coupa-Administratoren können API-Antwortfilter erstellen und verwalten, um Ausgaben, Anforderungen, Rechnungen, Bestellungen und Benutzerressourcen abzurufen. Sie können einen Standardfilter für eine oder mehrere dieser Ressourcen festlegen, um diesen Filter automatisch auf alle Anrufe auf diesem Controller anzuwenden, und Sie können einen Filter definieren, der auf mehrere Ressourcentypen angewendet wird. Sie können den API-Filter auf der gleichen API-Filter-Detailseite testen, die für die Konfiguration verwendet wird, und er führt auch eine Historie der Änderungen, die am Filter vorgenommen wurden.

Filter können auch mit Remote Approver-Callouts und Tax Engine-Callouts verwendet werden. Mit Aufrufen dieser Typen können Sie einen Filter angeben, um die an diese Endpunkte gesendete Nachricht zu vereinfachen.

Die neu hinzugefügten Felder innerhalb der APIs werden nur in API-Antworten angezeigt, wenn sie von einem bestimmten Feld begleitet werden, das in API-Antwortfiltern oder dem Abfrageparameter "Felder" erwähnt wird.

Was wir dachten

Die standardmäßigen API-Antworten von Coupa können mehr Informationen enthalten, als Ihre Systeme von Drittanbietern benötigen. Sie können viele Ebenen von Assoziationen zurückgeben, die Ihr Service möglicherweise nicht benötigt.

Callouts können auch mehr Informationen senden, als für einen Remote-Genehmigungsdienst oder einen Steuerdienst benötigt werden. Mit Filtern, die für diese Aufruftypen festgelegt sind, können Sie angeben, welche Ressourcenfelder im Nachrichtentext gesendet werden.

Ihre API-Antwortfilter können die Ausgabe der Anrufantwort reduzieren, sodass sie genau das sendet, was Ihr Dienst benötigt, ohne den Overhead, der erforderlich ist, um mehr zu verarbeiten, als Ihr externer Dienst benötigt. 

API-Antwortfilter können für die folgenden Ressourcen erstellt werden:

  • Rechnungen
  • Bestellköpfe
  • Bestellpositionen
  • Benutzer
  • Ausgabenüberschriften
  • Spesenpositionen
  • Anforderungen

Die Seite zur Erstellung von API-Filtern ermöglicht eine schnelle Iteration und führt einen Änderungsverlauf,sodass Sie Ihren Filter schnell testen, die Antwort überprüfen und ändern können, um genau das zu erhalten, was Sie benötigen.

So funktioniert es

Wenn Coupa-API-Filter verwendet werden, um das für die Antwort benötigte Datenvolumen einzuschränken, bedeutet weniger gesendete Daten eine geringere Latenz in der Antwortzeit. Die Vereinfachung der Ausgabe auf das, was für die Systemintegration benötigt wird, reduziert sowohl die anfängliche menschliche Auswertungszeit als auch später die Rechenzeit für das Parsen und Verarbeiten. 

Coupa-Administratoren und Systemintegrationsbenutzer mit der Berechtigung api_filters/index können die Schnittstelle API-Antwortfilter unter Setup > Integrationen > API-Filter einsehen.

API Filters.png

Die anfänglich gesetzten Filter werden mit dem Muster "default_[ResourceName]_filter" beschriftet und sind voreingestellte Filter, die Best Practices darstellen. Diese Seed-Filter sind bereits abgeschnitten und enthalten nicht alle verfügbaren Felder (Attribute), sondern stellen die Felder dar, die am häufigsten für Integrationsbemühungen benötigt werden. Sie können weitere Ressourcenfelder hinzufügen oder entfernen, um den anfänglich gesetzten Satz zu ändern, indem Sie einen eigenen Filter erstellen oder den Standard-Ressourcenfilter bearbeiten.  

API-Filter Detail.png

Standard-API-Filter

Wenn aktiviert, wendet das Kontrollkästchen Standard den Filter auf alle API-Aufrufe an, um diese Ressource ABZURUFEN. Jede Ressource kann nur einen Standard-API-Filter haben.

Wenn das Kontrollkästchen Standard deaktiviert ist, kann dieser API-Filter verwendet werden, indem eine Abfragezeichenfolge param:?filter='[API-Filtername]' zum GET-Aufruf für diese Ressource hinzugefügt wird.

Filter

Der API-Filter ist positiv, was bedeutet, dass die aufgelisteten Attribute in der Antwort angezeigt werden. Fügen Sie diese Ressourcenattribute hinzu oder entfernen Sie sie, damit der Filter die Ressourcenobjektattribute an Ihr Drittanbietersystem weitergibt und vor dem Testen speichert. 

Die Filtersyntax ermöglicht auch die Verwendung mit mehr als einem Dokumenttyp. Standardmäßig enthält ein neuer Filter Attribute, die der im ersten Schritt beim Erstellen des Filters ausgewählten Ressource entsprechen. Sie können jedoch Filtertext hinzufügen, der auf andere Dokumenttypen angewendet werden soll. Wenn ein Aufruf oder Web-Hook einen API-Antwortfilter für ein anderes Dokument verwendet, wird die Filterspezifikation für das andere Dokument einfach ignoriert.

Nachfolgend finden Sie ein Screenshot-Beispiel für die Filtersyntax mit zwei hervorgehobenen Dokumenttypen. Unterhalb der Grafik können Sie klicken, um den gleichen Filter mit auswählbarem Text zu erweitern.

API-Antwort filter.png

Klicken Sie hier, um ein Beispiel für die Filtersyntax für Anforderungspositionen und Auftragszeilenänderungen mit auswählbarem Text anzuzeigen.
[
"id",
  "created_at",
  "updated_at",
  "need_by_date",
  "status",
  "submitted_at",
  "ship_to_attention",
  "line_count",
  "exported",
  "total",
  {
"custom_fields": [
"migrated_po_number",
      "last_integrated_successfully"
]
},
  {
"currency": [
"code
", "decimals"
]
},
  {
"requested_by": [
"id
", "login
", "fullname
", "email
", "work_level"
]
},
  {
"ship_to_address
": ["name
", "location_code
", "street1
", "street2
", "city
", "state
", "postal_code
", "vat_number
", "local_tax_number
", "company_code"
]
},
  {
"requisition_lines
": ["id
", "description
", "line_num
", "need_by_date
", "order_line_id
", "quantity
", "receipt_required
", "source_part_num
",
      "unspsc_code",
      "status",
      "total", "line_type
",
      "unit_price
", "dci_category
":
          ["name
": "," lookup
              "," name "
           
]
         
},
      {
" account ":
", ",
"
          code "]} segment_1",
          "segment_2",
          "segment_3",
          {
"account_type": [
"name"
           
]
         
}]},
      {
"ul_contract
": ["name
", "description
", "external_ref_num
"
]
},
      {"custom_fields
": ["ext_line_num
", "material_type
",
]
},
      {
"commodity": [
"name",
          "category", "subcategory
"
]
},
      {"account
_allocations":
          ["amount",
            "pct",
          {
"account"
: ["name
", "code",
              "segment_1",
              "segment_2",
                "segment_3",
              {
"account_type": ["name
"
               
           
]
             
         
}]},
      {
"attachments":
          ["id",
          "created_at",
          "updated_at
", "type
",
          "intent", "file",
          "file_file_name", "
file
_file
_
size"
]
},
         
      {"currency
": ["code
"]}, {
"supplier": [
"name",
          "display_name", "number
", "pcard_account
",
          {"custom_fields": [
           
"
payment
_
term_
list
"
       
]
     
},
  {"uom":
    "code"]}}, {"order_id",
     
      "created_id",
      "_at",
      "line_num",
      "description",
      "need_by_date",
      "order_header_change_id",
      "order_line_id",
      "price",
      "quantity",
      "total",
      "paid_amount",
      {
"custom_fields": {}
}
]
},
  {
"current_approval": [
"id",
      "approvable_type",
      "approvable_id",
      "delegate_id"
]
},
  {
"created_by": [
"id",
      "login",
      "fullname",
      "email",
      "work_level"
]
},
  {
"updated_by": [
"id",
      "login",
      "fullname",
      "email",
      "work_level"
]
},
  {
"preparer": [
"id",
      "login",
      "fullname",
      "email",
      "work_level"
]
}
]

Zurücksetzen

Sie können den Filter auf die ursprünglich gesetzten Werte zurücksetzen, wenn Sie ihn in seine ursprüngliche Liste zurücksetzen möchten, oder Sie können den Verlauf der Änderungen als Referenz erweitern.

Test

Sie können die Ausgabeantwort Ihres Filters überprüfen, indem Sie zuerst einen bekannten ID-Wert in das Feld Testfilter auf eingeben und dann auf TEST klicken.  Die gesamte Standardrollensicherheit gilt für das, was Sie mit dem Test sehen können, aber Ihr gespeicherter API-Filter antwortet mit der angegebenen Teilmenge von Parameterfeldern in einem leicht lesbaren JSON-Format.

Als Operator

Mit dem Feldabfrageoperator können Sie die gewünschten Felder im Antworttext übergeben. Das Format des  Feldwerts ist json. Bitte beachten Sie das folgende Beispiel:

?fields=["id","invoice_number",{"invoice_lines":["id","line_num"]}]

Verfügbarkeit

Diese Funktion ist für alle Coupa-Kunden verfügbar.