Erste Schritte mit CSO OpenAPI

Die CSO-API ermöglicht Ihnen das Erstellen, Aktualisieren und Abrufen von Daten in und von CSO. Die Einrichtung der API-Aufrufe ist Teil des Projekts zur Integration von CSO in ein System von Drittanbietern, um den Austausch von Daten zwischen den Systemen zu ermöglichen.

Weder die Anzahl der an die CSO-REST-API gesendeten Anfragen NOCH die Größe des auszutauschenden Datensatzes sind technisch begrenzt. Irgendwann werden CSO oder das andere System jedoch nicht in der Lage sein, die Anfragen effizient zu bearbeiten. Es empfiehlt sich, Offset- und Limit-Operatoren zu verwenden, um die Antwortzeiten zu verkürzen oder große Datenmengen in kleineren Teilen zu senden.

Terminologie und Syntax

Alle API-Aufrufe zum Austausch von Daten zwischen CSO und einer anderen Datenbank erfolgen über das https://-Protokoll. Die auszutauschenden Daten, die Ressource, werden durch den Namen des Datentyps oder Objekts, das sie enthält (Markt, Ereignis, Factsheet usw.), gefolgt von der ID des jeweiligen Objekts oder Datensatzes in CSO, gegebenenfalls in folgendem Format bezeichnet:

https://{name_of_cso_site}/api/{resource_name}/{resource_id}

Der Name einer Kunden-CSO-Website wäre {company_name}.cso.coupahost.com. Beachten Sie, dass der API-Aufruf die ID verwendet, um eine Ressource anzugeben, nicht den tatsächlichen Namen oder das Objekt oder den Datensatz.

Die API-Aufrufe werden im json (JavaScript Object Notation) -Format geschrieben. Dies ist ein leichtgewichtiges textbasiertes offenes Standardformat, das üblicherweise für Datenübertragungen zwischen Systemen verwendet wird. Obwohl json hauptsächlich für JavaScript-Anwendungen entwickelt wurde, ist es agnostisch gegenüber der Programmiersprache, und Parser und andere Tools sind für die meisten Sprachen verfügbar.

Authentifizierung

Die Authentifizierung für den Datenaustausch zwischen dem CSO-Server und einem Server eines Drittanbieters wird durch einen eindeutigen API-Schlüssel vermittelt. Der API-Schlüssel wird von Coupa generiert. Es wird in CSO gespeichert und mit einem API-Benutzer verknüpft. Der API-Schlüssel ist im Header aller API-Anfragen enthalten, X-CSO-API-KEY, und der Accept-Header muss mit dem Wert ‘application/json‘ gesetzt werden.

Anfragen

Nach der oben beschriebenen Syntax würde eine Anfrage an die CSO-API für die Felder in einem Faktenblatt mit der ID 342333 im Fall mit der ID 12312224 wie folgt aussehen:

https://{name_of_cso_site}/api/events/12312224/fact-sheets/342333/fields

Es kann mehrere Anfragen erfordern, um einen bestimmten Datensatz abzurufen, z. B. zuerst die Ereignisse abzurufen, um eine bestimmte Ereignis-ID abrufen zu können, und dann die Factsheets abzurufen, um sogar die ID des jeweiligen Factsheets abzurufen, von dem Sie Informationen zu den Feldern benötigen. Das externe System kann diese IDs speichern, um den Zugriff auf Felder und/oder Faktenzeilen in einer einzigen Anfrage zu ermöglichen.

Wenn Sie eines der Faktenfelder verwenden, um einen Zeitstempel, eine Aktualisierungssequenznummer oder eine andere Art von Flag zu speichern, können Sie nur die neuen Daten seit der letzten Aktualisierung abfragen, um Leistungsprobleme zu vermeiden.

Methoden anfordern

GET (Daten lesen)

DIE GET-ANFORDERUNG fragt die CSO-Datenbank ab und gibt die mit der Anforderung übereinstimmenden Informationen an das Drittanbietersystem zurück. Die Anzahl der zurückgegebenen Objekte ist auf 250 begrenzt. Die Reaktion kann durch Hinzufügen von Anforderungsparametern angepasst werden:

• Limit: Gibt die Anzahl der zurückzugebenden Objekte an;
• Offset: Gibt die Startposition im gefundenen Datensatz an, um die Anzahl der von Limit angegebenen Zeilen von dort zurückzugeben.

Beispiel: https://{name_of_cso_site}/api/markets?offset=10&limit=5 gibt die nächsten 5 Märkte ab Position 10 in der Liste der in CSO gefundenen Märkte zurück. Wenn es weniger als 15 Märkte gibt, werden weniger oder keine zurückgegeben.

PUT (Daten aktualisieren)

Die PUT-ANFORDERUNG bringt Daten aus dem Drittanbietersystem in den CSO, um vorhandene Daten zu aktualisieren.

Beispiel: api/markets/{id} aktualisiert den Markt mit der angegebenen ID, während api/markets alle Märkte aktualisiert, die (durch ihre ID:s) im Anfragetext angegeben sind.

Aktualisierungen werden auf nachsichtige Weise durchgeführt, d. h. wenn die Aktualisierung einer Ressource fehlschlägt, können die anderen erfolgreich sein.

BUCHEN (Daten erstellen oder einfügen)

Eine POST-ANFORDERUNG erstellt oder fügt Daten in CSO in die angegebene Ressource ein. Bei Erfolg wird die neue ID der Daten/Ressource zurückgegeben.

LÖSCHEN (Daten löschen)

Das Löschen von Daten wird für einige, aber nicht alle Ressourcentypen unterstützt. Es kann auf einer Ressource gleichzeitig oder als Massenoperation durchgeführt werden. Beachten Sie, dass die Daten vollständig und dauerhaft gelöscht werden und nicht im CSO wiederhergestellt werden können. Anders ausgedrückt: Verwenden SIE die Löschmethode mit großer Sorgfalt und Achtsamkeit.

Antworten

Antworten von der CSO-API umfassen einen Antwortcode und einen JSON-Text.

Code 200 ist der allgemeine Erfolgsindikator. POST-Anfragen enthielten auch Code 201, der den Erfolg beim Erstellen der angeforderten Daten anzeigt.

Fehler führen zu 4xx Antwortcodes. Der Fehler wird in der Regel durch Aufrufe ausgelöst, die nicht unterstützt oder erlaubt sind. Anfragen, die aus unbekannten Gründen fehlschlagen, geben den Code 500 zurück. Wenn eine Anforderung fehlschlägt, versuchen Sie nicht, sie erneut einzureichen – sie schlägt erneut fehl. Weitere Informationen zu Antwortcodes findest du hier.

Obwohl einige Parameter möglicherweise bearbeitet werden müssen, um Namenskollisionen usw. zu vermeiden, können Antworten aus einer GET-Anforderung in den meisten Fällen in den Texten einer PUT- oder POST-Anforderung übermittelt werden. Falls das Format für einen bestimmten Datentyp nicht bekannt ist, können Sie daher die API nutzen, um das richtige Format bereitzustellen.

API-Operatoren

Obwohl CSO mit riesigen Datenmengen umgehen kann, sind Sie möglicherweise nur an einer Teilmenge der Daten interessiert, die durch Ihre GET-Anfrage ABGERUFEN werden. Die CSO-API unterstützt Coupa-Standard-API-Operatoren, mit denen Sie die relevanten Daten herausfiltern können. Die Operatoren können kombiniert werden, um die Antworten zu verfeinern. Beachten Sie, dass alle Bedingungen übereinstimmen müssen, um ein bestimmtes Objekt oder einen bestimmten Datenpunkt abzurufen.

Beispiele für die Verwendung von Operatoren zum Filtern des Ergebnisses

Rufen Sie den Markt mit dem Namen A ab, falls vorhanden:

HOLEN SIE SICH auf https://{name_of_cso_site}/api/markets?name=A

Rufen Sie alle Märkte mit Namen ab, die den Text "europäisch" enthalten, falls vorhanden.

HOLEN SIE SICH auf https://{name_of_cso_site}/api/markets?name[contains]=european

Rufen Sie alle Märkte mit Namen ab, die mit ‘FTL’ beginnen, falls vorhanden:

HOLEN SIE SICH auf https://{name_of_cso_site}/api/markets?name[starts_with]=FTL

Rufen Sie alle Märkte mit Namen ab, die auf "2018" enden, falls vorhanden:

HOLEN SIE SICH auf https://{name_of_cso_site}/api/markets?name[ends_with]=2018

Rufen Sie die ersten 50 Ereignisse mit Namen ab, einschließlich der ‘LTL’, falls vorhanden:

HOLEN SIE SICH auf https://{name_of_cso_site}/api/events?limit=50&name[contains]=LTL

Dokumente

Das OpenAPI-Schema ist auf allen CSO-Sites unter https://{name_of_cso_site}/openapi.html verfügbar. Die Dokumentation listet die Objekte und Datentypen auf, auf die zugegriffen werden kann (Markt, Benutzer, Factsheet usw.) und die Anforderungen, die für jeden von ihnen zulässig sind. Durch Klicken auf eine Anforderung wird ein Schema geöffnet, das das JSON-Format beschreibt.

Beispiele als Verweis

Märkte abrufen

ZU https://{name_of_cso_site}/api/markets

Antwortcode: 200

Antworttext:

{

"gesamt": 70,

"markets": [

{

"id": "9219593111199654844",

"Name": "Markt A",

"Beschreibung": „Ein beschreibender Text.“

},

{

"id": "9219593111199654844",

"Name": "Markt B"

},

… 68 weitere Märkte.

]

}

Beachten Sie, dass die Beschreibung für Markt B weggelassen wird. Leere oder NULL-Werte sollten bei der Verwendung von json nicht gesendet werden.

Einen Markt erstellen

POSTEN Sie auf https://{name_of_cso_site}/api/markets

Anforderungstext:

{

"Name": "Erster Markt",

"Beschreibung": "Optionaler Text, der den Markt beschreibt."

}

Antwortcode: 201

Antworttext:

{

"result": [

{

"type": "api.post.added",

"Beschreibung": "1 Objekte erstellt."

}

],

"hinzugefügt": 1.

"markets": [

{

"id": "9219593535573352536"

}

]

}

Der Antwortkörper enthält die von CSO für den neuen Markt erstellte ID.

Einen Markt aktualisieren

Auf https SETZEN://{name_of_cso_site}/api/markets/{market_id}

Anforderungstext:

{

"Name": "Erster Markt mit aktualisiertem Namen"

}

Antwortcode: 200

Antworttext:

{

"result": [

{

"type": "api.put.updated",

"Beschreibung": "1 Objekte aktualisiert."

}

],

"aktualisiert": 1

}

Das Attribut "updated" enthält die Anzahl der Objekte, die durch die PUT-Anforderung aktualisiert WURDEN.