CSO OpenAPIを始めましょう

CSO APIを使用すると、CSO内および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 Object Notation)形式で記述されます。これは、システム間のデータ転送に一般的に使用される軽量のテキストベースのオープンスタンダードフォーマットです。主にJavaScriptアプリケーション用に開発されているにもかかわらず、JSONはプログラミング言語には関係なく、パーサーやその他のツールはほとんどの言語で利用できます。

認証

CSOサーバーとサードパーティサーバー間のデータ交換の認証は、一意のAPI鍵で仲介されます。API鍵はCoupaで生成されます。CSOに格納され、APIユーザーに関連付けられます。APIキーはすべてのAPI要求のヘッダーであるX - CSO - API - KEYに含まれ、Acceptヘッダーは値‘application/json‘で設定する必要があります。

申請

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

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

特定のデータセットを取得するには、いくつかの要求が必要になる場合があります。たとえば、最初にイベントを取得して特定のイベントIDを取得できるようにし、次にその中のファクトシートを取得して、フィールドに関する情報が必要な特定のファクトシートのIDを取得します。外部システムは、１つの単一の要求内のフィールド及び／または事実の行へのアクセスを可能にするために、それらのＩＤを記憶することが可能であり得る。

ファクトフィールドの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 ： s ）を更新します。

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

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

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

削除（データ削除）

データの削除は、一部のリソースタイプでサポートされていますが、一部のリソースタイプではサポートされていません。一度に1つのリソースで実行することも、一括操作として実行することもできます。データは完全かつ永久に削除され、CSOで再作成できないことに注意してください。つまり、削除方法は細心の注意とマインドフルネスを持って使用してください。

回答

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

コード200は一般的な成功の指標です。POST要求には、要求されたデータの作成に成功したことを示すコード201も含まれていた。

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

一部のパラメータは、名前の衝突などを回避するために編集する必要がある場合がありますが、GET要求からの応答は、ほとんどの場合、PUT要求またはPOST要求の本文で送信できます。特定のデータタイプのフォーマットがわからない場合は、APIを悪用して正しいフォーマットを提供できます。

APIオペレーター

CSOは膨大な量のデータを処理できますが、GETリクエストによって取得されたデータのサブセットのみに興味があるかもしれません。CSO APIはCoupa標準APIオペレーターをサポートしているため、関連するデータをフィルタリングすることができます。演算子を組み合わせて応答を微調整することができます。特定のオブジェクトまたはデータポイントを取得するには、すべての条件が一致する必要があることに注意してください。

演算子を使用して結果を絞り込む方法の例

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

Https ://{ name_of_cso_site }/ api/markets? name = Aで入手

「ヨーロッパ」というテキストを含む名前のあるすべての市場を取得します（ある場合）。

Https ://{ name_of_cso_site }/ api/markets? name [contains ]= europeanで入手

「FTL」で始まる名前のすべての市場を取得します（存在する場合） ：

Https :// {name_of_cso_site}/api/markets? name [starts_with] = FTLで入手

名前が「2018」で終わるすべての市場を取得します（存在する場合） ：

Https ://{ name_of_cso_site }/ api/markets? name [ends_with] = 2018で入手

存在する場合は、「LTL」を含む名前を持つ最初の50イベントを取得します。

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

回答本文：

{

"合計":節約しました。

"markets ": [

{

"ID ":"9219593111199654844 ",

"name ":"マーケットA ",

"description ":「説明文です。」

},

{

"ID ":"9219593111199654844 ",

"name ":「マーケットB」

},

...さらに68の市場があります。

]

}

マーケットBの説明が省略されていることに注意してください。JSONを使用している場合、空またはNULLの値を送信することはできません。

市場を作成

Https ://{ name_of_cso_site }/ api/marketsに投稿

申請本文：

{

"name ":"最初の市場",

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

}

回答コード：201

回答本文：

{

"result ": [

{

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

"DESCRIPTION ":"1件のオブジェクトが作成されました。"

}

],

"追加されました":1,

"markets ": [

{

"ID ":"9219593535573352536"

}

]

}

レスポンスボディには、新しい市場のためにCSOによって作成されたIDが含まれています。

市場を更新

Https ://{ name_of_cso_site }/ api/markets /{ market_id}に置く

要求本文:

{

"name ":「名前が変更された最初の市場」

}

回答コード：200

回答本文：

{

"result ": [

{

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

"description ":"1件のオブジェクトが更新されました。"

}

],

"更新済み":1

}

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