Salesforce B2C Commerce で利用できる b2c-tools について

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

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


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

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



## b2c-tools を使ってみる

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

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

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

1. 任意のフォルダで下記コマンドを実行しnpm環境を作成
    ```sh
    npm init
    ```

1. b2c-tools のインストール
    1. 現在プライベートのレポジトリであり、Github からインストールするためには認証が必要になるので、[Github の README](https://github.com/SalesforceCommerceCloud/b2c-tools?tab=readme-ov-file#installation) にある手順で設定を行います。

    1. 下記コマンドでヘルプが表示されていればインストール完了です。

    ```sh
    npx b2c-tools --help
    ```



### 〜〜まず準備（OCAPIとWebDAV権限設定編）〜〜

b2c-toolsはOCAPIやWebDAVを利用するので権限の設定をしていきます。

1. [Account Manager](https://account.demandware.com/) から作成したAPIクライアントを作成。または既存のクライアントに追加
    * Rolesには `Saleforce Commerce API`が入っており、作成したサンドボックスのURLが設定されていること。(サンドボックスのURLは`setup-script/sandbox.json`から確認できます。)
    * Default Scopeに下記の内容が入っていること。
    * ```
        roles
        tenantFilter
        openId
       ````
    **※ 作成後に生成されるID（UUID）と設定したパスワードは後にdw.jsonで利用するのでメモしておいてください。**

    ![APIClient.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2110894/b4a3fc4b-41f2-f532-2114-5e5e8c5675ca.png)



1. WebDAVのアクセスキーの生成
    * 以前紹介したQiitaの「[WebDAVへアクセスするためのアクセスキーを生成](https://qiita.com/syunyama/items/21c71ac9c49b332e126d#3--webdav%E3%81%B8%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%81%99%E3%82%8B%E3%81%9F%E3%82%81%E3%81%AE%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%82%AD%E3%83%BC%E3%82%92%E7%94%9F%E6%88%90)」項目をご覧ください。
1. dw.jsonの作成
    ```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の「[デプロイバージョンの作成](https://qiita.com/syunyama/items/21c71ac9c49b332e126d#2%E3%83%87%E3%83%97%E3%83%AD%E3%82%A4%E3%83%90%E3%83%BC%E3%82%B8%E3%83%A7%E3%83%B3%E3%81%AE%E4%BD%9C%E6%88%90)」項目をご覧ください。
1. WebDAVパーミッションの作成
    * Business Manager で **管理 > 組織 > クライアントの WebDAV 許可** に遷移して、下記のようなJSONフォーマットで利用するリーソースの権限を設定し、保存する。 `client_id` にはAccess Managerで作成したAPIクライアントのIDを入力する。（でに何かしらの値が入っている場合は、clients内に追加する）

    ```json
    {
        "clients": [
            {
                "client_id": "{Your Client ID}",
                "permissions": [
                  {
                    "path": "/Logs",
                    "operations": [
                      "read"
                    ]
                  },
                  {
                    "path": "/impex",
                    "operations": [
                            "read_write"
                    ]
                  },
                  {
                    "path": "/cartridges",
                    "operations": [
                        "read_write"
                    ]
                  }
                ]
            }
        ]
    }
    ```



1. OCAPIの権限設定
    * Business Manager で **管理 > サイトの開発 > Open Commerce API 設定** に遷移して、今回はData系のAPIなので **「タイプの選択」項目は「データ」** を選択した上で、下記のようなJSONフォーマットで利用するリーソースの権限を設定し、保存する。 `client_id` にはAccess Managerで作成したAPIクライアントのIDを入力する。(すでに何かしらの値が入っている場合は、clients内に追加する）

    ```json
    {
    "_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` フォルダにダウンロードされます。

```sh
npx b2c-tools export site -o migrations
```

![data_export (1).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2110894/025a959e-0d36-00c9-ac1b-29a0255fff64.png)



* 下記コマンドを実行するとカートリッジが `./cartridges` フォルダにダウンロードされます。

```sh
npx b2c-tools code download -o ./cartridges
```


**サイト情報、カートリッジダウンロード後のフォルダ：**
![スクリーンショット 2022-09-07 11.14.23.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2110894/e91c7078-5f4d-1d99-c99a-9cef9ed1ce59.png)




### 〜〜サイト情報のインポート〜〜

#### 複数のサイト情報をインポートしたい場合

下記のコマンドでは `./migrations` フォルダにある複数のサイト情報をインポートします

```sh
npx b2c-tools import migrate --migrations-dir=migrations
```

例： Githubで管理していたサイト情報を新しく作成するサンドボックスに一括反映させる



#### 特定のサイト情報をインポートしたい場合


下記のコマンドでは `./migrations/20220906T014657383Z_export` フォルダのサイト情報をインポートします

```sh
npx b2c-tools import run migrations/20220906T014657383Z_export
```

例： チームメンバーがGithub上のジョブのXMLファイルを作成してその内容を自分のサンドボックスに反映させたい



### 〜〜Page Designer のエクスポート〜〜

下記のコマンドでは `./migrations` フォルダにRefArchSharedLibraryライブラリのhomepageとcontactというページIDのページをダウンロードします。

```sh
npx b2c-tools export page -o migrations --library RefArchSharedLibrary homepage contact
```

例：他の開発者が作成したページを自分のサンドボックスに反映させたい。（ダウンロード後、上記「サイト情報のインポート」で取り扱ったコマンドで自身のサンドボックスにインポートする必要があります）



### 〜〜カートリッジのアップロード〜〜

#### コマンド実行したフォルダ内にあるカートリッジを全てアップロードしたい場合

```sh
npx b2c-tools code deploy
```

例：Githubで管理しているカートリッジを自分のサンドボックスに一括で適用したい


#### コマンド実行したフォルダ内にある特定のカートリッジアップロードしたい場合

下記のコマンドでは実行したフォルダ内にある app_storefront_base と modules をアップロードします。

```sh
npx b2c-tools code deploy --cartridge app_storefront_base modules
```

例：Githubで管理している特定カートリッジを自分のサンドボックスに適用したい

**※ アップロード先のバージョンは `dw.json` 内の `code-version` に書かれているものを利用します。**




### 〜〜機能単位での開発ツール〜〜

一つの機能を作るのに、「カートリッジ(cartridges)」、「サイト情報(migrations)」、「依存関係にあるカートリッジ(dependencies)」が必要になりますが、それを機能単位でアップロードや削除ができ、さらに複数の機能の開発時の切り替えといった管理もできます。これらを利用して既存サイトへの新しい機能の追加の際に使うことができます。

ここは少し複雑なので、説明は割愛します。詳細については[Featuresに関するGithubのREADME](https://github.com/SalesforceCommerceCloud/b2c-tools/blob/main/docs/FEATURES.md)を参照してください。
また、[実装サンプル](https://github.com/SalesforceCommerceCloud/b2c-tools/tree/main/examples/features/exampleFeature)もあるのでそちらも参考にしてください。



### 〜〜ログの確認〜〜

#### 全てのログをリアルタイムで確認出力

```sh
npx b2c-tools tail
```

#### 特定のログをリアルタイムで確認

下記のコマンドは「customerror」または「error」で始まるログファイルのログをリアルタイムで確認できます。

```sh
npx b2c-tools tail -f customerror error
```




### 〜〜使用するインスタンスの管理〜〜

dw.jsonを操作することで環境を管理するコマンドです。

#### dw.jsonの作成

```sh
npx b2c-tools instance setup
```

#### 現在使用中のインスタンス情報の確認

```sh
npx b2c-tools instance debug
```

#### デフォルトで利用するインスタンスを設定する

```sh
npx b2c-tools instance set

## 下記コマンドではabcdというインスタンスをどフォルトにしている
npx b2c-tools instance set abcd
```

#### 環境のBusiness Managerを開く

```sh
npx b2c-tools instance open
```



### 〜〜コマンドの拡張〜〜

上記で紹介したコマンドに加えて、[API](https://github.com/SalesforceCommerceCloud/b2c-tools/blob/main/docs/API.md)を利用したコマンドの追加やログの出力先の変更など、コマンド拡張することができます。
詳細は[コマンドの拡張に関するREADME](https://github.com/SalesforceCommerceCloud/b2c-tools/blob/main/docs/EXTENDING.md)を参照ください。