※ これから記載する事項は、私が所属する会社とは一切関係のない事柄です。

今回の記事ではカートリッジの開発やCI/CDに利用できるツールである、b2c-tools (Account Managerへのアクセス必要)を紹介いたします。

b2c-tools って何ができるの？

サイト情報のインポート
サイト情報のエクスポート
Page Designer のエクスポート
カートリッジのアップロード
カートリッジのダウンロード
機能単位での開発ツール
ログの確認
使用するインスタンスの管理
コマンドの拡張

b2c-tools を使ってみる

既存の環境に対して使用していきます。

〜〜まず準備（ローカル環境設定編）〜〜

npm環境とコマンドのインストールを行います。

任意のフォルダで下記コマンドを実行しnpm環境を作成
```
npm init
```
b2c-tools のインストール
1. 現在プライベートのレポジトリであり、Github からインストールするためには認証が必要になるので、Github の README にある手順で設定を行います。
2. 下記コマンドでヘルプが表示されていればインストール完了です。
```
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で利用するのでメモしておいてください。
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"
                ]
              }
            ]
        }
    ]
}

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"
        }
    ]
    }
]
}

〜〜まず準備（サイト情報とカートリッジのダウンロード編）〜〜

下記コマンドを実行すると（画像のような）ブラウザが立ち上がり、必要な情報を選択することで、それらの情報が ./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を参照ください。