CSO OpenAPIの開始

CSO APIを使用すると、CSOとの間でデータを作成、更新、取得できます。APIコールの設定は、CSOをサードパーティのシステムに統合してシステム間でのデータ交換を可能にするプロジェクトの一部です。

CSO REST APIに送信されるリクエストの数や、交換されるデータセットのサイズに技術的な制限はありません。ただし、CSOまたは他のシステムがリクエストを効率的に処理できない場合があります。オフセット演算子と制限演算子を使用して応答時間を短縮するか、大量のデータをより小さな単位で送信することをお勧めします。

用語と構文

CSOと別のデータベース間でデータを交換するためのすべてのAPIコールは、 https:// プロトコル。交換するデータ、 リソース は、それを保持するデータタイプまたはオブジェクト（マーケット、イベント、ファクトシートなど）の名前の後に、CSO内の特定のオブジェクトまたはデータセットのIDが続きます（該当する場合）。以下の形式です。

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

顧客のCSOサイトの名前は次のようになります {company_name}.cso.coupahost.com 。APIコールは、実際の名前やオブジェクトまたはデータセットではなく、IDを使用してリソースを指定することに注意してください。

APIコールはJSON（JavaScriptオブジェクト表記）形式で書かれています。これは、システム間のデータ転送によく使用される、軽量なテキストベースのオープン標準フォーマットです。JSONは主にJavaScriptアプリケーション向けに開発されていますが、プログラミング言語とは異なり、パーサーやその他のツールはほとんどの言語で使用できます。

認証

CSOサーバとサードパーティサーバ間のデータ交換のための認証は、一意のAPIキーによって仲介されます。APIキーはCoupaによって生成されます。CSOに保存され、 APIユーザー 。APIキーはすべてのAPIリクエストのヘッダーに含まれており、X-CSO-API-KEYとAcceptヘッダーには「application/json」の値を設定する必要があります。

申請

上記の構文に従って、ID 342333を持つイベントのID 12312224を持つファクトシートのフィールドに対するCSO APIへのリクエストは、次のようになります。

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

特定のデータセットを取得するにはいくつかの要求が必要になる場合があります。たとえば、最初にイベントを取得して特定のイベントIDを取得してから、その中のファクトシートを取得して、フィールドに関する情報が必要な特定のファクトシートのIDを取得するなどです。外部システムはこれらのIDを保存して、1つのリクエストでフィールドや事実行へのアクセスを許可できます。

ファクトフィールドの1つを使用して、タイムスタンプ、更新シーケンス番号、または別のタイプのフラグを保持すると、パフォーマンスの問題を回避するために、最終更新以降の新規データのみを問い合わせることができます。

リクエストメソッド

GET（データの読込）

GETリクエストはCSOデータベースにクエリを実行し、リクエストに一致する情報をサードパーティのシステムに返します。返されるオブジェクトの数は250個に制限されています。応答は、要求パラメーターを追加することで微調整できます。

• 制限：返すオブジェクトの数を指定します。
• オフセット：見つかったデータセットの開始位置を指定し、そこからlimitで指定した行数を返します。

例 で指定します。 https://{name_of_cso_site}/api/markets?offset=10&limit=5 csoで見つかった市場のリスト内で、ポジション10から始まる次の5つの市場を返します。マーケットの数が15未満の場合、返されるマーケットは少ないかゼロです。

PUT（データの更新）

PUTリクエストは、サードパーティシステムからCSOにデータを取り込み、既存のデータを更新します。

例 で指定します。 api/markets/{id} 指定されたIDで市場を更新しますが、api/marketsはリクエスト本文で指定されたすべての市場（IDで）を更新します。

更新は寛大な方法で行われます。たとえば、1つのリソースの更新に失敗した場合、他のリソースは正常に更新される可能性があります。

POST（データの作成または挿入）

POSTリクエストは、指定されたリソースにCSOでデータを作成または挿入します。成功した場合、データ/リソースの新しいIDが返されます。

DELETE（データの削除）

一部のリソースタイプではデータの削除がサポートされていますが、すべてのリソースタイプでサポートされているわけではありません。これは、一度に1つのリソースに対して実行することも、一括操作として実行することもできます。データは完全かつ完全に削除され、CSOで再作成することはできません。つまり、DELETEメソッドは慎重に使用してください。

回答

CSO APIからの応答には、応答コードとJSON本文が含まれます。

コード200は一般的な正常インジケーターです。POSTリクエストには、要求されたデータの作成が成功したことを示すコード201も含まれています。

エラーの結果、4xx応答コードになります。このエラーは通常、サポートされていない、または許可されていないコールによってトリガーされます。不明な理由で失敗した申請はコード500を返します。リクエストが失敗した場合、再送信しないでください。再送信すると再び失敗します。返答コードの詳細については、こちらをご覧ください ここ 。

名前の競合などを回避するために一部のパラメータの編集が必要になる場合がありますが、ほとんどの場合、GETリクエストからの応答はPUTまたはPOSTリクエストの本文で送信できます。特定のデータタイプの形式が不明な場合は、APIを利用して正しい形式を提供できます。

API演算子

CSOは大量のデータを処理できますが、関心があるのはGETリクエストによって取得されたデータのサブセットのみです。CSO APIはCoupaをサポートしています 標準API演算子 関連データを除外できます。演算子を組み合わせて回答を完成させることができます。特定のオブジェクトまたはデータポイントを取得するには、すべての条件が一致する必要があります。

演算子を使用して結果をフィルタリングする方法の例

Aという名前の市場が存在する場合は取得します。

GET on https://{name_of_cso_site}/api/markets?name=A

テキスト「european」を含む名前を持つすべての市場があれば取得します。

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

「FTL」で始まる名前の市場があれば、すべて取得します。

GET on https://{name_of_cso_site}/api/markets?name[starts_with]=FTL

「2018」で終わる名前のすべての市場がある場合は、取得します。

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

「LTL」を含む名前の最初の50個のイベントがある場合はそれを取得します。

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

文書

OpenAPIスキーマは、以下のすべてのCSOサイトで使用できます https://{name_of_cso_site}/openapi.html 。ドキュメントには、アクセス可能なオブジェクトとデータタイプ（マーケット、ユーザー、ファクトシートなど）と、それぞれに許可されている申請が一覧表示されています。リクエストをクリックすると、JSON形式を説明するスキーマが開きます。

参照例

マーケットを入手

取得 https://{name_of_cso_site}/api/markets

返答コード：200

返答本文：

{

「合計」:70、

「市場」:[

{

"id": "9219593111199654844",

"名前": "マーケットA",

「説明」:「説明文」。

}、

{

"id": "9219593111199654844",

"名前": "マーケットB"

}、

...さらに68の市場が追加されました。

]

}

説明はマーケットBには残されています。JSONを使用する場合、空またはnull値は送信されません。

市場を作成

投稿先 https://{name_of_cso_site}/api/markets

申請本文：

{

"名前":"First Market",

「説明」:「市場を説明するオプションのテキスト」。

}

返答コード：201

返答本文：

{

「結果」:[

{

"タイプ": "api.post.added",

"説明": "1つのオブジェクトが作成されました。"

}

]、

「追加済み」:1,

「市場」:[

{

"id": "9219593535573352536"

}

]

}

返答本文には、新規市場向けにCSOによって作成されたIDが含まれます。

市場を更新

プット先 https://{name_of_cso_site}/api/markets/{market_id}

申請本文：

{

"名前": "名前が更新された最初のマーケット"

}

返答コード：200

返答本文：

{

「結果」:[

{

"タイプ": "api.put.updated",

"説明": "1つのオブジェクトが更新されました。"

}

]、

「更新済み」: 1

}

「updated」属性には、PUTリクエストによって更新されたオブジェクトの数が含まれます。