Erste Schritte mit CSO OpenAPI

Mit der CSO-API können Sie Daten in und aus CSO erstellen, aktualisieren und abrufen. Die Einrichtung der API-Aufrufe ist Teil des Projekts zur Integration von CSO in ein Drittanbietersystem, um den Datenaustausch zwischen den Systemen zu ermöglichen.

Weder für die Anzahl der an die CSO REST API gesendeten Anfragen noch für die Größe des auszutauschenden Datensatzes gibt es technische Grenzen. Doch irgendwann wird CSO oder das andere System nicht in der Lage sein, die Anfragen effizient zu bearbeiten. Es empfiehlt sich, Offset- und Grenzoperatoren zu verwenden, um die Antwortzeiten zu verkürzen oder große Datenmengen in kleineren Einheiten zu senden.

Terminologie und Syntax

Alle API-Aufrufe zum Datenaustausch zwischen CSO und einer anderen Datenbank erfolgen unter Verwendung des https:// Protokoll. Die auszutauschenden Daten, Ressource wird durch den Namen des Datentyps oder des Objekts, das ihn enthält (Markt, Ausschreibung, Faktenblatt usw.), gefolgt von der ID des jeweiligen Objekts oder Datensatzes in CSO, ggf. im folgenden Format:

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

Der Name einer Kunden-CSO-Site 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-Format (JavaScript Object Notation) geschrieben. Dies ist ein leichtes textbasiertes offenes Standardformat, das häufig 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 Drittanbieter-Server wird durch einen eindeutigen API-Schlüssel vermittelt. Der API-Schlüssel wird von Coupa generiert. Sie wird in CSO gespeichert und mit einem API-Benutzer , Der API-Schlüssel ist in der Kopfzeile aller API-Anforderungen enthalten, X-CSO-API-KEY, und der Accept-Header muss mit dem Wert "application/json" festgelegt werden.

Anforderungen

Entsprechend der oben beschriebenen Syntax würde eine Anforderung an die CSO-API für die Felder in einem Faktenblatt mit der ID 342333 in der Ausschreibung mit der ID 12312224 wie folgt aussehen:

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

Es kann mehrere Anfragen dauern, einen bestimmten Datensatz zu erhalten, z. B. zuerst die Ereignisse abrufen, um eine bestimmte Ereignis-ID zu erhalten, dann die Faktenblätter abrufen, um sogar die ID des bestimmten Faktenblatts zu erhalten, aus dem Sie Informationen über die Felder 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 Markierung zu enthalten, können Sie nur die neuen Daten seit der letzten Aktualisierung abfragen, um Leistungsprobleme zu vermeiden.

Anforderungsmethoden

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 Antwort kann durch Hinzufügen von Anforderungsparametern angepasst werden:

• Grenzwert: gibt die Anzahl der zurückzugebenden Objekte an;
• Offset: spezifiziert die Startposition im gefundenen Datensatz, um die Anzahl der Zeilen, die von dort aus durch Limit spezifiziert sind, 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 Märkte in CSO zurück. Wenn es weniger als 15 Märkte gibt, werden weniger oder keiner zurückgegeben.

PUT (Daten aktualisieren)

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

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

Aktualisierungen erfolgen nachsichtig, d. h. wenn die Aktualisierung einer Ressource fehlschlägt, können die anderen erfolgreich sein.

POST (Daten erstellen oder einfügen)

Eine POST-Anforderung erstellt oder fügt Daten in CSO in die angegebene Ressource ein. Wenn erfolgreich, wird die neue ID der Daten/Ressource zurückgegeben.

DELETE (Daten löschen)

Das Löschen von Daten wird für einige, aber nicht alle Ressourcentypen unterstützt. Dies kann für eine Ressource gleichzeitig oder als Massenvorgang erfolgen. Beachten Sie, dass die Daten vollständig und dauerhaft gelöscht werden und nicht in CSO neu erstellt werden können. Mit anderen Worten, verwenden Sie die DELETE-Methode mit großer Sorgfalt und Achtsamkeit.

Antworten

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

Code 200 ist der allgemeine Erfolgsindikator. POST-Anforderungen enthielten auch Code 201, der darauf hinweist, dass die angeforderten Daten erfolgreich erstellt wurden.

Fehler führen zu 4xx Antwortcodes. Der Fehler wird normalerweise durch Aufrufe ausgelöst, die nicht unterstützt oder zugelassen werden. Anforderungen, die aus unbekannten Gründen fehlschlagen, geben Code 500 zurück. Wenn eine Anforderung fehlschlägt, versuchen Sie nicht, sie erneut zu übermitteln - sie schlägt erneut fehl. Weitere Details zu Antwortcodes finden Sie hier ,

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

API-Operatoren

Obwohl CSO große Datenmengen verarbeiten kann, sind Sie möglicherweise nur an einer Teilmenge der Daten interessiert, die von Ihrer GET-Anfrage abgerufen wurden. Die CSO-API unterstützt Coupa Standard-API-Operatoren Hier können Sie die relevanten Daten herausfiltern. 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:

GET on 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.

GET on https://{name_of_cso_site}/api/markets?name[contains]=european

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

GET on 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:

GET on https://{name_of_cso_site}/api/markets?name[ends_with]=2018

Rufen Sie die ersten 50 Events mit Namen wie "LTL" ab, falls vorhanden:

GET on https://{name_of_cso_site}/api/events?limit=50&name[contains]=LTL

Dokumentation

Das OpenAPI-Schema ist auf allen CSO-Sites unter https://{name_of_cso_site}/openapi.html , In der Dokumentation sind die Objekte und Datentypen aufgeführt, auf die zugegriffen werden kann (Markt, Benutzer, Faktenblatt usw.), sowie 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 für Referenz

Märkte erobern

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

Antwortcode: 200

Antworttext:

{

"gesamt": 70,

"Märkte": [

{

"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 ausgelassen wird. Leere oder Nullwerte sollten bei Verwendung von JSON nicht gesendet werden.

Einen Markt kreieren

POST an https://{name_of_cso_site}/api/markets

Anforderungstext:

{

"name": "First Market",

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

}

Antwortcode: 201

Antworttext:

{

"Ergebnis": [

{

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

"Beschreibung": "1 Objekte erstellt."

}

],

"hinzugefügt": 1,

"Märkte": [

{

"id": "9219593535573352536"

}

]

}

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

Markt aktualisieren

PUT zu https://{name_of_cso_site}/api/markets/{market_id}

Anforderungstext:

{

"name": "Erster Markt mit aktualisiertem Namen"

}

Antwortcode: 200

Antworttext:

{

"Ergebnis": [

{

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

"Beschreibung": "1 Objekte aktualisiert."

}

],

"aktualisiert": 1

}

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