WebAPI説明を追加

content/commerble/development/webapi/_index.md

@@ -0,0 +1,77 @@
+---
+title: "Web API"
+weight: 30
+description: 
+---
+
+# Web API
+
+この章では、Commerbleの管理用Web APIについて説明します。
+
+このAPIは管理用であり、カート処理用のWeb APIでは無いことに留意が必要です。
+
+つまりこれはJAMStackで構成されたECサイト(フロントサイト)から使用する購入APIとしては機能しないことを意味します。  
+そのようなAPIが必要な場合は[カスタマイズ実績：カートのWeb API化]をご参照ください。
+
+## エンドポイント
+
+CommerbleではWEB APIをREST形式で提供しています。REST仕様は[OData]に則っています。
+
+ODataのバージョンは旧フィードAPIがV3、現行API(data)がV4を提供しています。
+
+|          エンドポイント          |           種類           | ODataバージョン |   状態   |
+| :------------------------------- | :----------------------: | :-------------: | :------: |
+| ~/ec.feed/odata.svc              |         EC Feed          |       V3        |   廃止   |
+| ~/ec.feed.v2/odata.svc           |         EC Feed          |       V3        | 廃止予定 |
+| ~/ec.feed.v3/odata.svc           |         EC Feed          |       V3        | 廃止予定 |
+| ~/ec.feed.v4/odata.svc           |         EC Feed          |       V3        |          |
+| ~/ec.feed.v5/odata.svc           |         EC Feed          |       V3        |          |
+| ~/cms.feed/list/odata.svc        |        CMS  Feed         |       V3        |   廃止   |
+| ~/cms.feed.v2/list/odata.svc     |        CMS  Feed         |       V3        |          |
+| ~/cms.feed/metadata/odata.svc    |        Meta  Feed        |       V3        |   廃止   |
+| ~/cms.feed.v2/metadata/odata.svc |        Meta  Feed        |       V3        |          |
+| ~/data/ec                        |         EC Feed          |       V4        |          |
+| ~/data/cms                       |        CMS  Feed         |       V4        |          |
+| ~/data/meta                      |        Meta Feed         |       V4        |          |
+| ~/data/query                     |       Custom View        |       V4        |          |
+| ~/data/template/validate         | Front Template Validator |        -        |          |
+| ~/data/query/validate            | Query Template Validator |        -        |          |
+| ~/data/mail/validate             | Mail Template Validator  |        -        |          |
+
+- EC Feed : 共通スキーマのデータにアクセスできます
+- CMS Feed : 各テナントごとに設定したスキーマのデータにアクセスできます
+- Meta Feed : テンプレートデータ及びルーティングにアクセスできます
+- Custom View : カスタムビューテンプレートを実行できます
+- Front Template Validator : フロントテンプレートを検証できます
+- Query Template Validator : カスタムビューテンプレートを検証できます
+- Mail Template Validator : カスタムビューテンプレートを検証できます
+
+エンドポイントのフルURLと認証情報は契約後にご提供いたします。
+
+## 認証
+
+FeedRead/Write ロールが付与された管理サイトアカウントをベーシック認証で使用します。
+
+同一アカウントで3回パスワードが間違われた場合はアカウントロックされます。
+
+## 制限
+
+Web APIの利用に対して、単位時間当たりのアクセス可能数などの利用制限はありません。 業務ドメインに基づいて、必要であれば、1000リクエスト、1万リクエスト、10万リクエストしていただけます。
+
+ただし、、更新する必要のないデータを頻繁に入れ替えるなど、大量のAPIコールを日常的に実施することは避けてください。
+
+モニタリングでそれらの兆候が観測された場合は、Commerble社から確認・状況の改善のご協力をお願いすることがあります。
+
+## リンク
+
+- [EC Feedを使用する](./data/#ec-feed)
+- [CMS Feedを使用する](./data/#cms-feed)
+- [Meta Feedを使用する](./data/#meta-feed)
+- [Custom Viewを使用する](./query/)
+- [Front Template Validatorを使用する](./template/#cshtml)
+- [Mail Template Validatorを使用する](./template/#mail)
+- [Query Template Validatorを使用する](./template/#csx)
+
+
+[OData]: https://www.odata.org/ "OData"
+[カスタマイズ実績：カートのWeb API化]: ../../achievement/cartapi/ "カートのWeb API化"

content/commerble/development/webapi/data.md

@@ -0,0 +1,125 @@
+---
+title: "データAPI"
+weight: 1
+description: 
+---
+
+# データAPI
+
+この章では、Commerbleの提供するWeb APIのうちデータAPIについて説明します。
+
+データAPIでは、Commerbleに保存されているデータにアクセスすることができます。
+
+また、アクセスするデータによって以下の3つのエンドポイントに分かれています。
+
+- EC Feed
+- CMS Feed
+- Meta Feed
+
+データAPIは全て[OData]として提供されます。[OData]の仕様は、[OData V4 Documentation]もしくは[OData V3 Documentation]をご確認ください。
+
+## EC Feed
+
+EC Feedでは、共通スキーマの情報を作成、更新、削除できます。 操作可能なデータはODataメタデータを確認ください。
+
+|     エンドポイント     |            メタデータ            |             補足             |
+| :--------------------- | :------------------------------- | :--------------------------- |
+| ~/data/ec              | ~/data/ec/$metadata              | 現行エンドポイント、OData V4 |
+| ~/ec.feed.v5/odata.svc | ~/ec.feed.v5/odata.svc/$metadata | 旧エンドポイント、OData V3   |
+
+またメタデータに合わせて、[データ：ECデータ]もご確認ください。
+
+## CMS Feed
+
+CMS Feedでは、テナントごとにカスタムされたスキーマの情報を作成、更新、削除できます。
+
+はじめに、使用するCMSスキーマを策定する必要があります。詳しくは、[CMSスキーマの定義例]をご確認ください。
+
+スキーマの定義を作成後、オーダーカスタムをご依頼いただきCommerble社側でスキーマを反映いたします。
+反映までが完了しない状態でメタデータにアクセスしても操作可能なデータが無いことに留意が必要です。
+
+CMSスキーマの反映後は、操作可能なデータはODataメタデータを確認ください。
+
+|        エンドポイント        |               メタデータ               |             補足             |
+| :--------------------------- | :------------------------------------- | :--------------------------- |
+| ~/data/cms                   | ~/data/cms/$metadata                   | 現行エンドポイント、OData V4 |
+| ~/cms.feed.v2/list/odata.svc | ~/cms.feed.v2/list/odata.svc/$metadata | 旧エンドポイント、OData V3   |
+
+## Meta Feed
+
+Meta Feedでは、テンプレートやルーティングなどのCMS機能にかかわる共通スキーマ情報を作成、更新、削除できます。操作可能なデータはODataメタデータを確認ください。
+
+|          エンドポイント          |                 メタデータ                 |             補足             |
+| :------------------------------- | :----------------------------------------- | :--------------------------- |
+| ~/data/meta                      | ~/data/meta/$metadata                      | 現行エンドポイント、OData V4 |
+| ~/cms.feed.v2/metadata/odata.svc | ~/cms.feed.v2/metadata/odata.svc/$metadata | 旧エンドポイント、OData V3   |
+
+またメタデータに合わせて、[データ：メタデータ]もご確認ください。
+
+## サンプル
+
+以下にEC Feedで商品を追加する例を示します。
+
+```
+--- リクエスト ---
+POST ~/data/ec/Products HTTP/1.1
+Accept: application/json
+Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxx
+Content-Type: application/json
+
+{
+  "Name": "サンプル商品1-黒-S",
+  "ProductType": 0,
+  "SalesStart": "2020-01-01T00:00:00+09:00",
+  "SalesEnd": null,
+  "ReleaseDate": null,
+  "ReReleaseDate": null,
+  "ExternalId1": "SAMPLE001",
+  "ExternalId2": "BLK-S",
+  "ExternalId3": null,
+  "ExternalId4": null,
+  "UnitPrice": 1000,
+  "TaxationPrice": 1000,
+  "SalesPatternId": 1,
+  "DeliveryPatternId": 1,
+  "SalesStatus": 0
+}
+
+--- レスポンス ---
+HTTP/1.1 201 Created
+Cache-Control: no-cache
+Content-Length: 519
+Content-Type: application/json;charset=utf-8
+Location: ~/data/ec/Products(1)
+
+{
+    "@odata.context": "~/data/ec/$metadata#Products/$entity",
+    "Id": 1,
+    "Name": "サンプル商品1-黒-S",
+    "ProductType": 0,
+    "SalesStart": "2020-01-01T00:00:00+09:00",
+    "SalesEnd": null,
+    "ReleaseDate": null,
+    "ReReleaseDate": null,
+    "ExternalId1": "SAMPLE001",
+    "ExternalId2": "BLK-S",
+    "ExternalId3": null,
+    "ExternalId4": null,
+    "UnitPrice": 1000,
+    "SalesPatternId": 1,
+    "DeliveryPatternId": 1,
+    "SetOnly": null,
+    "Cero": null,
+    "MemoId": null,
+    "SalesStatus": 0,
+    "TaxationPrice": 1000,
+    "OrderedProduct": null
+}
+```
+
+[OData]: https://www.odata.org/ "OData"
+[OData V4 Documentation]: https://www.odata.org/documentation/ "OData V4"
+[OData V3 Documentation]: https://www.odata.org/documentation/odata-version-3-0/ "OData V3"
+[データ：ECデータ]: ../../data/ec/ "ECデータ"
+[CMSスキーマの定義例]: ../../data/cms/#定義例 "CMSデータ"
+[データ：メタデータ]: ../../data/meta/ "メタデータ"

content/commerble/development/webapi/query.md

@@ -0,0 +1,105 @@
+---
+title: "クエリAPI"
+weight: 3
+description: 
+---
+
+# クエリAPI
+
+この章では、クエリAPIについて説明します。
+
+クエリAPIではカスタムビューテンプレートを実行することができます。
+カスタムビューテンプレートとは`csx`タイプで作成されたテンプレートです。
+
+カスタムビューテンプレートで許可されたデータベースアクセスは読み取りのみです。
+
+## 保存されたテンプレートの実行
+
+|  項目  |                       |      説明      |
+| :----- | :-------------------- | :------------- |
+| Method | GET                   |                |
+| Route  | ~/data/query/render   |                |
+| Query  | x-www-form-urlencoded |                |
+|        | name                  | テンプレート名 |
+
+**例**  
+```
+--- テンプレートの作成---
+POST ~/data/meta/Templates HTTP/1.1
+Authorization: Basic xxxxxxxxxxxxxxxxxxx
+Content-Type: application/json
+{
+    "Name": "QuerySample",
+    "Text": "new []{ new { i = 0, s = \"0\" }, new { i = 1, s = \"1\" }, new { i = 2, s = \"2\" } }",
+    "Type": "csx"
+}
+
+--- リクエスト ---
+GET ~/data/query/render?name=QuerySample HTTP/1.1
+Authorization: Basic xxxxxxxxxxxxxxxxxxx
+
+--- レスポンス ---
+HTTP/1.1 200 OK
+Content-Length: 49
+Content-Type: application/json; charset=utf-8
+
+[{"i":0,"s":"0"},{"i":1,"s":"1"},{"i":2,"s":"2"}]
+```
+
+## テンプレートを渡して実行
+
+|  項目  |                     |           説明           |
+| :----- | :------------------ | :----------------------- |
+| Method | POST                |                          |
+| Route  | ~/data/query/render |                          |
+| Body   | JSON オブジェクト   |                          |
+|        | Script              | テンプレート内容(String) |
+
+**例** 
+```
+--- リクエスト ---
+POST ~/data/query/render HTTP/1.1
+Authorization: Basic xxxxxxxxxxxxxxxxxxx
+Content-Type: application/json
+Accept: application/json
+
+{
+    "Script": "new []{ new { i = 0, s = \"0\" }, new { i = 1, s = \"1\" }, new { i = 2, s = \"2\" } }"
+}
+
+--- レスポンス ---
+HTTP/1.1 200 OK
+Content-Length: 49
+Content-Type: application/json; charset=utf-8
+
+[{"i":0,"s":"0"},{"i":1,"s":"1"},{"i":2,"s":"2"}]
+```
+
+## CSV形式で取得
+
+`Accept`ヘッダフィールドに`text/csv`を指定してリクエストする、もしくは、リクエストURLに`$format=csv`クエリパラメータを付与することでCSVファイルをダウンロードすることが可能です。 
+
+このCSVファイルはExcelで開くために、BOM付きUTF8エンコードとして出力されます。
+
+**例** 
+```
+--- リクエスト:Acceptヘッダフィールド ---
+GET ~/data/query/render?name=QuerySample HTTP/1.1
+Authorization: Basic xxxxxxxxxxxxxxxxxxx
+Accept: text/csv
+
+--- リクエスト:$formatクエリパラメータ ---
+GET ~/data/query/render?name=QuerySample&$format=csv HTTP/1.1
+Authorization: Basic xxxxxxxxxxxxxxxxxxx
+
+--- レスポンス ---
+HTTP/1.1 200 OK
+Content-Length: 149
+Content-Type: text/csv
+
+"i","s"
+0,"0"
+1,"1"
+2,"2"
+
+```