データ API の概要
InterSystems Supply Chain Orchestrator™ は、データの作成、更新、削除、および取得のための APIOpens in a new tab を提供します。ここでは、この API の概要を説明します。
API の URL パターン
すべての API 呼び出しは以下の同じ URL パターンに従います。
GET {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/OBJECT_PATH?parameters
POST {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/OBJECT_PATH
GET/PUT/DELETE {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/OBJECT_PATH/uid
以下はその説明です。
-
{{IRIS-SERVER}} の部分は、InterSystems IRIS® インスタンスのサーバ情報です。ローカルで導入されたサーバでは、http://localhost:52773 のようになります。
-
{{DATAMODEL-PATH}} の部分は、API ベース URL です。例えば、/api/scdata/v1 のようになります。
-
OBJECT_PATH の部分は、小文字の複数形のオブジェクト名です。例えば、salesorders や customers のようになります。すべてのオブジェクト値については、以下の表を参照してください。
-
最初の URL パターンは、オブジェクトのデータを取得するか、一連のパラメータを使用してオブジェクトを検索します。任意のオブジェクトの属性を検索条件で使用できます。
-
2 番目の URL パターンは、新しいオブジェクト・レコードを作成します。要求の本文には、新しいオブジェクトの JSON 文字列を含める必要があります。
-
3 番目の URL パターンは、uid (外部の主キー) によりオブジェクト・レコードを取得、更新、または削除します。
以下に例を示します。
-
ステータスが Open または PartialShip であるすべての販売注文の検索 :
GET {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/salesorders?orderStatus=Open,PartialShip
-
新規顧客の作成 :
POST {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/customers
この際に、要求の本文に以下の JSON を含めます。
{ "uid" : "CUST-TEST-101", "name" : "Google", "type" : "HighTech", "contact" : "Ming", "url" : "https://google.com" }
-
uid 値が SUP-SHIP-1001 である供給出荷レコードの取得 :
GET {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/supplyshipments/SUP-SHIP-1001
-
位置レコードの更新 :
PUT {{IRIS-SERVER}}/{{DATAMODEL-PATH}}/locations/LOC-PLANT-002
この際に、要求の本文に新しい位置の JSON データを含めます。
検索 API
検索は、1 つまたは複数の URL パラメータを使用した GET API でサポートされます。各パラメータは、1 つの検索条件にマップされます。複数のパラメータが使用される場合、パラメータ条件は論理 AND 演算を使用して結合されます。例えば、以下はすべての Lenovo ラップトップ製品を検索します。
GET /products?brand=Lenovo&category=laptop
各パラメータ名はプライマリ・オブジェクトの属性名と正確に一致する必要があります。場合によっては、セカンダリ・オブジェクト (含まれているオブジェクトや参照オブジェクト) の属性も使用できます。例えば、一部の製品属性を注文検索で使用できます。
検索パラメータ値は、以下に示すように、単一値、値のリスト、または値の範囲にすることができます。
-
単一値。これは最も単純な検索条件で、parameterName=value の形式を使用します。パラメータが文字列または文字列のリストである場合、値のマッチングで大文字と小文字は区別されません。そのため、brand=lenovo と brand=Lenovo は同じです。
-
値のリスト。リスト内の任意の値との一致を必要とする条件の場合、値のリストをコンマ区切りの文字列として指定できます。例えば、Lenovo ブランドか Dell ブランドの製品を見つけるには、brand=Lenovo,Dell を使用できます。すべてのデータ型、文字列、日付、および数字に対してリストを使用できます。
-
値の範囲。日付および数値 (通貨を含む) の場合、検索パラメータで範囲を使用できます。範囲は、.. (2 つのドット) で区切られた 2 つの値で指定します。min..max の形式を取り、両方の値が範囲に含まれます。例えば、price=100..200 は、100 (100 を含む) ~ 200 (200 を含む) の範囲の価格のすべてのレコードを検索します。2 つの範囲の境界値は常に必須ではなく、片方がない場合、境界がないことを意味します。例えば、price=..200 は、価格が 200 以下であるレコードを意味し、price=100.. は価格が 100 以上であるレコードを意味します。
-
NULL 値。どのデータ型でも、属性が設定されていない (つまり NULL 値である) レコードと、何らかの値が設定された属性 (つまり NULL ではない) を持つレコードを検索することができます。そのような場合、任意の属性に対して 2 つの特殊な文字列値 NULL および NOTNULL を使用できます。例えば、attr1=NULL&attr2=NOTNULL のようになります。
例えば、次の呼び出しでは、Lenovo または Dell のブランドで、500 ~ 1000 の価格範囲のすべてのラップトップ・コンピュータを検索します。
GET /products?category=laptop&brand=Lenovo,Dell&price=500..1000
結果の並べ替え
API 呼び出しによって複数のレコードが返される場合、並べ替えパラメータ sortBy を指定することで応答データの順序を定義できます。このパラメータの値は、返されるプライマリ・オブジェクトの属性名のコンマ区切りリストである必要があります。
例えば、次の API 呼び出しは、応答で注文リストをどのように並べ替えるかを定義します。
GET /salesorders?sortBy=customer,orderValue
これは、最初は顧客順で、次に注文額順で並べ替えが実行されるよう定義します。
既定では、並べ替えは昇順で行われます。順序を降順に変更するには、以下の例に示すように属性名の前に - 記号を使用します。この例では、最初に顧客によって昇順で並べ替え、その後 orderValue によって降順で並べ替えます。
GET /salesorders?sortBy=customer,-orderValue
既定の並べ替え
要求の URL で並べ替えパラメータが指定されない場合、返されるプライマリ・オブジェクトに基づいて、既定の並べ替えが適用されます。以下の表は、各オブジェクト・タイプの既定の並べ替えパラメータを示しています。
オブジェクト | URL パス | 既定の並べ替え属性 |
---|---|---|
Carrier | carriers | name |
Customer | customers | name |
Supplier | suppliers | name |
Product | products | name |
Location | locations | locationName |
BillOfMaterial | billofmaterials | productId、parentItemId |
InventoryThreshold | inventorythresholds | siteLocationId、productId |
Milestone | milestones | ID |
ProductInventory | productinventories | siteLocationId、productId |
ProductSupplier | productsuppliers | productId |
SupplyPlan | supplyplans | locationId、productId |
DemandPlan | demandplans | locationId、productId |
SalesOrder | salesorders | -orderPlacedDate |
SalesOrderLine | salesorderlines | orderId、lineNumber |
SalesShipment | salesshipments | -actualShipDate |
SalesShipmentLine | salesshipmentlines | shipmentId、lineNumber |
PurchaseOrder | purchaseorders | -orderPlacedDate |
PurchaseOrderLine | purchaseorderlines | orderId、lineNumber |
SupplyShipment | supplyshipments | -actualShipDate |
SupplyShipmentLine | supplyshipmentlines | shipmentId、lineNumber |
ManufacturingOrder | manufacturingorders | -orderEntryDate |
結果のページ付け
既定では、複数のレコードを返す API 呼び出しは、指定された条件と一致する最初の 100 件のレコードを返します。ページ付けパラメータを使用して、追加のレコードまたはより大きなレコード・セットを取得できます。ページ付けパラメータにより、例えばリソース (メモリ、ネットワーク帯域幅など) を過剰に消費したり、パフォーマンスの問題を引き起こすことなく、Web UI でテーブルを生成するために必要な制御が可能になります。
ページ付けパラメータは、以下のとおりです。
-
pageSize. このパラメータは、API 呼び出しで返されるレコードの最大数を定義します。返されるレコードの実際の数は、この値以下になります。既定値は 100 で、許可される最大値は 1000 です。
-
pageIndex. このパラメータは、応答で返されるページ・インデックス (0 から始まる) を指定します。既定値は 0 です。
例えば、以下の API 呼び出しは、最初の 200 件の注文をスキップし、次の 100 件の注文を、注文額で並べ替えて返します。
GET /salesorders?sortBy=orderValue&pageSize=100&pageIndex=2
応答でページ付けを使用して部分的なレコードのみが返される場合、応答内で以下の HTTP ヘッダ・パラメータが生成されます。これらの値を使用して、UI のページ付けロジックを制御します。
-
pageSize.要求パス・パラメータで指定されている場合は同じ値です。要求で明示的に指定されていない場合は、既定値が返されます。
-
pageIndex.要求パス・パラメータで指定されている場合は同じ値です。要求で明示的に指定されていない場合は、既定値が返されます。
-
returnCount. 現在の応答で返されるレコード数。この値は pageSize 以下です。
日付および日付/時刻の形式
日付または日付/時刻の属性については、メッセージの JSON 本文内で指定するか、または HTTP パラメータ内で指定するかに関係なく、ISO 8601 形式で値を指定する必要があります。
以下は、その例です。日付属性の場合 :
2021-02-28
日付/時刻属性の場合 (以下の 2 つの値は同等です) :
2021-12-15T13:23:15-05:00
2021-12-15T18:23:15Z
タイム・ゾーンの情報が指定されていない場合、UTC 時刻を使用するものと見なされます。例えば、2021-05-24T08:30:00 は 2021-05-24T08:30:00Z と同様に扱われます。