From a2ab34899a5a12e968c981dc20e630eb5d78da89 Mon Sep 17 00:00:00 2001 From: yoshiyuki taniguchi Date: Fri, 25 Sep 2020 12:54:31 +0900 Subject: [PATCH] =?UTF-8?q?WebAPI=E8=AA=AC=E6=98=8E=E3=82=92=E8=BF=BD?= =?UTF-8?q?=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../commerble/development/webapi/_index.md | 77 ++++++++ content/commerble/development/webapi/data.md | 125 +++++++++++++ content/commerble/development/webapi/query.md | 105 +++++++++++ .../commerble/development/webapi/template.md | 167 ++++++++++++++++++ 4 files changed, 474 insertions(+) create mode 100644 content/commerble/development/webapi/_index.md create mode 100644 content/commerble/development/webapi/data.md create mode 100644 content/commerble/development/webapi/query.md create mode 100644 content/commerble/development/webapi/template.md diff --git a/content/commerble/development/webapi/_index.md b/content/commerble/development/webapi/_index.md new file mode 100644 index 0000000..6b7876b --- /dev/null +++ b/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化" diff --git a/content/commerble/development/webapi/data.md b/content/commerble/development/webapi/data.md new file mode 100644 index 0000000..6ee3519 --- /dev/null +++ b/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/ "メタデータ" diff --git a/content/commerble/development/webapi/query.md b/content/commerble/development/webapi/query.md new file mode 100644 index 0000000..b06eeb2 --- /dev/null +++ b/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" + +``` \ No newline at end of file diff --git a/content/commerble/development/webapi/template.md b/content/commerble/development/webapi/template.md new file mode 100644 index 0000000..1d91dc6 --- /dev/null +++ b/content/commerble/development/webapi/template.md @@ -0,0 +1,167 @@ +--- +title: "テンプレートAPI" +weight: 2 +description: +--- + +# テンプレートAPI + +この章では、各種テンプレートの検証APIについて説明します。 + +Commerbleにおけるテンプレートの種類と説明を下表に示します。 + +| テンプレート | 説明 | +| :----------- | :-------------------------------------------------- | +| template | Commerble独自のテンプレート記法を用いたテンプレート | +| cshtml | [Razor構文]を使用したWebページ用テンプレート | +| mail | [Razor構文]を使用したメール用テンプレート | +| csx | [C# Scripting]を使用したカスタムビューテンプレート | + +これらのテンプレートのうち、テンプレートAPIを使用することによって、`cshtml`,`mail`,`csx`のテンプレート内容を検証することができます。[Meta Feed API]を使用して、テンプレートを更新する前に、この検証APIを使用してテンプレート内容を検証することで、コンパイルエラーによるWebページのダウンを回避することができます。 + +## cshtml + +| 項目 | | 説明 | +| :----- | :----------------------- | :---------------------------------- | +| Method | POST | | +| Route | ~/data/template/validate | | +| Body | JSON オブジェクト | | +| | Template | テンプレート内容(String) | +| | WithViews | 共通テンプレートを結合する(Boolean) | + +**例** +``` +--- リクエスト:検証結果OK --- +POST ~/data/template/validate HTTP/1.1 +Authorization: Basic xxxxxxxxxxxxxxxxxxx +Content-Type: application/json + +{ + "Template": "@{var msg = \"Hello, Validate!\";}

@msg

", + "WithViews": false +} + +--- レスポンス:検証結果OK --- +HTTP/1.1 200 OK +Content-Length: 0 +``` +``` +--- リクエスト:検証結果NG --- +POST ~/data/template/validate HTTP/1.1 +Authorization: Basic xxxxxxxxxxxxxxxxxxx +Content-Type: application/json + +{ + "Template": "

@msg

", + "WithViews": false +} +--- レスポンス:検証結果NG --- +HTTP/1.1 400 BadRequest +Content-Length: 91 +Content-Type: application/json; charset=utf-8 + +{ + "Message": "- error: (38, 6) The name 'msg' does not exist in the current context" +} +``` + +## mail + +| 項目 | | 説明 | +| :----- | :------------------- | :----------------------- | +| Method | POST | | +| Route | ~/data/mail/validate | | +| Body | JSON オブジェクト | | +| | Template | テンプレート内容(String) | + +**例** +``` +--- リクエスト:検証結果OK --- +POST ~/data/mail/validate HTTP/1.1 +Authorization: Basic xxxxxxxxxxxxxxxxxxx +Content-Type: application/json + +{ + "Template": "@{Message.Subject = \"お買い上げありがとうございます。\";} Thank you :)" +} + +--- レスポンス:検証結果OK --- +HTTP/1.1 200 OK +Content-Length: 21 +Content-Type: application/json; charset=utf-8 + +{ + "Message": "Success" +} +``` +``` +--- リクエスト:検証結果NG --- +POST ~/data/mail/validate HTTP/1.1 +Authorization: Basic xxxxxxxxxxxxxxxxxxx +Content-Type: application/json + +{ + "Template": "@{Message.Subject = \"お買い上げありがとうございます。\";} @msg" +} + +--- レスポンス:検証結果NG --- +HTTP/1.1 400 BadRequest +Content-Length: 892 +Content-Type: application/json; charset=utf-8 + +{ + "Message": "Errors while compiling a Template.\nPlease try the following to solve the situation:\n * If the problem is about missing/invalid references or multiple defines either try to load \n the missing references manually (in the compiling appdomain!) or\n Specify your references manually by providing your own IReferenceResolver implementation.\n See https://antaris.github.io/RazorEngine/ReferenceResolver.html for details.\n Currently all references have to be available as files!\n * If you get 'class' does not contain a definition for 'member': \n try another modelType (for example 'null' to make the model dynamic).\n NOTE: You CANNOT use typeof(dynamic) to make the model dynamic!\n Or try to use static instead of anonymous/dynamic types.\nMore details about the error:\n - error: (27, 48) The name 'msg' does not exist in the current context\n" +} +``` +## csx + +| 項目 | | 説明 | +| :----- | :-------------------- | :----------------------- | +| Method | POST | | +| Route | ~/data/query/validate | | +| Body | JSON オブジェクト | | +| | Script | テンプレート内容(String) | + +**例** +``` +--- リクエスト:検証結果OK --- +POST ~/data/query/validate HTTP/1.1 +Authorization: Basic xxxxxxxxxxxxxxxxxxx +Content-Type: application/json + +{ + "Template": "using System.Linq;\n new []{0,1,2,3,4}.Where(i => (i % 2) == 0)" +} + +--- レスポンス:検証結果OK --- +HTTP/1.1 200 OK +Content-Length: 21 +Content-Type: application/json; charset=utf-8 + +{ + "Message": "Success" +} +``` +``` +--- リクエスト:検証結果NG --- +POST ~/data/query/validate HTTP/1.1 +Authorization: Basic xxxxxxxxxxxxxxxxxxx +Content-Type: application/json + +{ + "Script": "new []{0,1,2,3,4}.Where(i => (i % 2) == 0)" +} + +--- レスポンス:検証結果NG --- +HTTP/1.1 400 BadRequest +Content-Length: 342 +Content-Type: application/json; charset=utf-8 + +{ + "Message": "(1,19): error CS1061: 'int[]' に 'Where' の定義が含まれておらず、型 'int[]' の最初の引数を受け付けるアクセス可能な拡張メソッド 'Where' が見つかりませんでした。using ディレクティブまたはアセンブリ参照が不足していないことを確認してください。]" +} +``` + +[Razor構文]: https://docs.microsoft.com/aspnet/mvc/mvc3#the-razor-view-engine "Razor" +[C# Scripting]: https://docs.microsoft.com/archive/msdn-magazine/2016/january/essential-net-csharp-scripting "C# Scripting" +[Meta Feed API]: ./data/#meta-feed "Meta Feed" \ No newline at end of file