※ これから記載する事項は、私が所属する会社とは一切関係のない事柄です。
今回の記事ではカートリッジの開発やCI/CDに利用できるツールである、b2c-tools (Account Managerへのアクセス必要)を紹介いたします。
b2c-tools って何ができるの?
- サイト情報のインポート
- サイト情報のエクスポート
- Page Designer のエクスポート
- カートリッジのアップロード
- カートリッジのダウンロード
- 機能単位での開発ツール
- ログの確認
- 使用するインスタンスの管理
- コマンドの拡張
b2c-tools を使ってみる
既存の環境に対して使用していきます。
〜〜まず準備(ローカル環境設定編)〜〜
npm環境とコマンドのインストールを行います。
-
任意のフォルダで下記コマンドを実行しnpm環境を作成
npm init
-
b2c-tools のインストール
-
現在プライベートのレポジトリであり、Github からインストールするためには認証が必要になるので、Github の README にある手順で設定を行います。
-
下記コマンドでヘルプが表示されていればインストール完了です。
npx b2c-tools --help
-
〜〜まず準備(OCAPIとWebDAV権限設定編)〜〜
b2c-toolsはOCAPIやWebDAVを利用するので権限の設定をしていきます。
-
Account Manager から作成したAPIクライアントを作成。または既存のクライアントに追加
- Rolesには
Saleforce Commerce API
が入っており、作成したサンドボックスのURLが設定されていること。(サンドボックスのURLはsetup-script/sandbox.json
から確認できます。) - Default Scopeに下記の内容が入っていること。
-
roles tenantFilter openId
※ 作成後に生成されるID(UUID)と設定したパスワードは後にdw.jsonで利用するのでメモしておいてください。
- Rolesには
-
WebDAVのアクセスキーの生成
- 以前紹介したQiitaの「WebDAVへアクセスするためのアクセスキーを生成」項目をご覧ください。
-
dw.jsonの作成
dw.json{ "hostname": "XXXX.dx.commercecloud.salesforce.com", "username": "{Account Manager ユーザのEメール}", "password": "{WebDAVのアクセスキー}", "code-version": "{利用しているコードバージョン}", "client-id": "{API クライアントのID(UUID)}", "client-secret": "{API クライアントのパスワード}" }
※ コードバージョンについては以前紹介したQiitaの「デプロイバージョンの作成」項目をご覧ください。
-
WebDAVパーミッションの作成
- Business Manager で 管理 > 組織 > クライアントの WebDAV 許可 に遷移して、下記のようなJSONフォーマットで利用するリーソースの権限を設定し、保存する。
client_id
にはAccess Managerで作成したAPIクライアントのIDを入力する。(でに何かしらの値が入っている場合は、clients内に追加する)
{ "clients": [ { "client_id": "{Your Client ID}", "permissions": [ { "path": "/Logs", "operations": [ "read" ] }, { "path": "/impex", "operations": [ "read_write" ] }, { "path": "/cartridges", "operations": [ "read_write" ] } ] } ] }
- Business Manager で 管理 > 組織 > クライアントの WebDAV 許可 に遷移して、下記のようなJSONフォーマットで利用するリーソースの権限を設定し、保存する。
-
OCAPIの権限設定
- Business Manager で 管理 > サイトの開発 > Open Commerce API 設定 に遷移して、今回はData系のAPIなので 「タイプの選択」項目は「データ」 を選択した上で、下記のようなJSONフォーマットで利用するリーソースの権限を設定し、保存する。
client_id
にはAccess Managerで作成したAPIクライアントのIDを入力する。(すでに何かしらの値が入っている場合は、clients内に追加する)
{ "_v": "18.1", "clients": [ { "client_id": "{Your Client ID}", "resources": [ { "methods": ["get"], "read_attributes": "(**)", "resource_id": "/code_versions", "write_attributes": "(**)" }, { "methods": ["patch", "delete"], "read_attributes": "(**)", "resource_id": "/code_versions/*", "write_attributes": "(**)" }, { "methods": ["post"], "read_attributes": "(**)", "resource_id": "/jobs/*/executions", "write_attributes": "(**)" }, { "methods": ["get"], "read_attributes": "(**)", "resource_id": "/jobs/*/executions/*", "write_attributes": "(**)" }, { "methods": ["get"], "read_attributes": "(**)", "resource_id": "/sites" }, { "methods": ["get"], "read_attributes": "(**)", "resource_id": "/catalogs" }, { "methods": ["get"], "read_attributes": "(**)", "resource_id": "/inventory_lists" } ] } ] }
- Business Manager で 管理 > サイトの開発 > Open Commerce API 設定 に遷移して、今回はData系のAPIなので 「タイプの選択」項目は「データ」 を選択した上で、下記のようなJSONフォーマットで利用するリーソースの権限を設定し、保存する。
〜〜まず準備(サイト情報とカートリッジのダウンロード編)〜〜
- 下記コマンドを実行すると(画像のような)ブラウザが立ち上がり、必要な情報を選択することで、それらの情報が
./migrations
フォルダにダウンロードされます。
npx b2c-tools export site -o migrations
- 下記コマンドを実行するとカートリッジが
./cartridges
フォルダにダウンロードされます。
npx b2c-tools code download -o ./cartridges
〜〜サイト情報のインポート〜〜
複数のサイト情報をインポートしたい場合
下記のコマンドでは ./migrations
フォルダにある複数のサイト情報をインポートします
npx b2c-tools import migrate --migrations-dir=migrations
例: Githubで管理していたサイト情報を新しく作成するサンドボックスに一括反映させる
特定のサイト情報をインポートしたい場合
下記のコマンドでは ./migrations/20220906T014657383Z_export
フォルダのサイト情報をインポートします
npx b2c-tools import run migrations/20220906T014657383Z_export
例: チームメンバーがGithub上のジョブのXMLファイルを作成してその内容を自分のサンドボックスに反映させたい
〜〜Page Designer のエクスポート〜〜
下記のコマンドでは ./migrations
フォルダにRefArchSharedLibraryライブラリのhomepageとcontactというページIDのページをダウンロードします。
npx b2c-tools export page -o migrations --library RefArchSharedLibrary homepage contact
例:他の開発者が作成したページを自分のサンドボックスに反映させたい。(ダウンロード後、上記「サイト情報のインポート」で取り扱ったコマンドで自身のサンドボックスにインポートする必要があります)
〜〜カートリッジのアップロード〜〜
コマンド実行したフォルダ内にあるカートリッジを全てアップロードしたい場合
npx b2c-tools code deploy
例:Githubで管理しているカートリッジを自分のサンドボックスに一括で適用したい
コマンド実行したフォルダ内にある特定のカートリッジアップロードしたい場合
下記のコマンドでは実行したフォルダ内にある app_storefront_base と modules をアップロードします。
npx b2c-tools code deploy --cartridge app_storefront_base modules
例:Githubで管理している特定カートリッジを自分のサンドボックスに適用したい
※ アップロード先のバージョンは dw.json
内の code-version
に書かれているものを利用します。
〜〜機能単位での開発ツール〜〜
一つの機能を作るのに、「カートリッジ(cartridges)」、「サイト情報(migrations)」、「依存関係にあるカートリッジ(dependencies)」が必要になりますが、それを機能単位でアップロードや削除ができ、さらに複数の機能の開発時の切り替えといった管理もできます。これらを利用して既存サイトへの新しい機能の追加の際に使うことができます。
ここは少し複雑なので、説明は割愛します。詳細についてはFeaturesに関するGithubのREADMEを参照してください。
また、実装サンプルもあるのでそちらも参考にしてください。
〜〜ログの確認〜〜
全てのログをリアルタイムで確認出力
npx b2c-tools tail
特定のログをリアルタイムで確認
下記のコマンドは「customerror」または「error」で始まるログファイルのログをリアルタイムで確認できます。
npx b2c-tools tail -f customerror error
〜〜使用するインスタンスの管理〜〜
dw.jsonを操作することで環境を管理するコマンドです。
dw.jsonの作成
npx b2c-tools instance setup
現在使用中のインスタンス情報の確認
npx b2c-tools instance debug
デフォルトで利用するインスタンスを設定する
npx b2c-tools instance set
## 下記コマンドではabcdというインスタンスをどフォルトにしている
npx b2c-tools instance set abcd
環境のBusiness Managerを開く
npx b2c-tools instance open
〜〜コマンドの拡張〜〜
上記で紹介したコマンドに加えて、APIを利用したコマンドの追加やログの出力先の変更など、コマンド拡張することができます。
詳細はコマンドの拡張に関するREADMEを参照ください。