はじめに
Salesforce CLIの sf コマンドを使うと、ブラウザの画面操作だけでなく、ターミナルからSalesforce組織へログインしたり、SOQLを実行したり、レコードを登録・更新・削除したりできます。
この記事では、最初の入門として 単一レコードの操作 に絞って整理します。
Salesforce CLIには、SOQL検索、SOSL検索、単一レコードの取得・登録・更新・削除、CSVを使った一括処理、Bulk API 2.0を使った大量データ操作なども用意されています。ただ、最初から一括処理まで入れると見通しが悪くなるため、今回は「CLIから1件の取引先を作って、確認して、更新して、削除する」ところまでを扱います。
本記事は個人の整理メモです。削除コマンドも扱うため、Developer EditionまたはSandboxなどの検証用組織で試してください。本番組織では実行しないことをおすすめします。
Salesforceの通常のレコード削除では、削除されたレコードはごみ箱に入ります。ただし、業務組織では復元確認や影響調査が必要になるため、この記事では検証用データだけを対象にします。
今回試すこと
この記事では次の流れで試します。
- Salesforce CLIのインストール確認
- Developer EditionまたはSandboxへログイン
- 接続済み組織を確認
- SOQLで取引先を検索
- 取引先レコードを1件登録
- 登録したレコードを取得
- 登録したレコードを更新
- 登録したレコードを削除
- Salesforce CLIに保存された認証を解除
サンプルでは、ログイン時に my-dev-org というエイリアスを付けます。
コマンド例はmacOS/LinuxのシェルやGit Bashなどを想定し、行継続に \ を使っています。Windows PowerShellで複数行に分ける場合は、行末の \ ではなくバッククォート ` を使うか、1行にまとめて実行してください。
Salesforce CLIを準備する
まず、Salesforce CLIが使えるか確認します。
sf --version
バージョンが表示されれば準備OKです。
未インストールの場合は、Salesforce公式のインストールページからSalesforce CLIをインストールします。
Salesforce組織へログインする
次のコマンドでSalesforce組織へログインします。
sf org login web --alias my-dev-org --set-default
ブラウザが開くので、Developer EditionまたはSandboxのユーザーでログインします。ログインが完了すると、CLIからその組織を操作できるようになります。
ログイン時にエイリアスを設定しておくと、後続のコマンドで対象組織を指定しやすくなります。今回は my-dev-org という名前で扱います。
Sandboxへログインする場合は、必要に応じて --instance-url を指定します。
sf org login web \
--alias my-dev-org \
--set-default \
--instance-url https://test.salesforce.com
https://test.salesforce.com からログインできない場合は、SandboxのMy Domain URLを指定します。組織のログインポリシーによっては、My Domain URLの使用が必要です。
sf org login web \
--alias my-dev-org \
--set-default \
--instance-url https://<MyDomain名>--<Sandbox名>.sandbox.my.salesforce.com
接続している組織を確認する
ログインできたら、接続済みの組織を確認します。
sf org list
sf org list では、作成または認証済みの組織を一覧表示できます。
複数の組織にログインしている場合、どの組織がデフォルトになっているかも確認しておくと安心です。
SOQLで取引先を検索する
まずは取引先オブジェクト Account をSOQLで検索します。
sf data query \
--query "SELECT Id, Name, Industry FROM Account LIMIT 10" \
--target-org my-dev-org
sf data query はSOQLを実行するコマンドです。結果は標準では人間が読みやすい形式で表示されます。
JSON形式で表示したい場合は --json を付けます。
sf data query \
--query "SELECT Id, Name, Industry FROM Account LIMIT 10" \
--target-org my-dev-org \
--json
CSV形式でターミナルに表示したい場合は --result-format csv を使います。
sf data query \
--query "SELECT Id, Name, Industry FROM Account LIMIT 10" \
--target-org my-dev-org \
--result-format csv
CSVファイルとして保存したい場合は、--output-file も指定します。
sf data query \
--query "SELECT Id, Name, Industry FROM Account LIMIT 10" \
--target-org my-dev-org \
--result-format csv \
--output-file accounts.csv
なお、大量データを扱う場合は注意が必要です。現在のSalesforce CLI公式リファレンスでは、検索結果が10,000件を超える場合、Bulk API 2.0を使用する sf data export bulk コマンドの利用が案内されています。この記事では入門として少数件の検索に留めます。
取引先レコードを登録する
次に、検証用の取引先を1件登録します。
sf data create record \
--sobject Account \
--values "Name='CLIテスト株式会社' Industry=Technology" \
--target-org my-dev-org
sf data create record は、指定したオブジェクトにレコードを1件登録するコマンドです。
--sobject にはオブジェクトのAPI参照名を指定します。取引先の場合は Account です。
--values には項目と値を 項目API参照名=値 の形で指定します。複数項目を指定する場合はスペース区切りにします。値に空白が含まれる場合は、上の例のように値をシングルクォートで囲みます。
実行結果には、作成されたレコードIDが表示されます。以降の取得・更新・削除で使うため、控えておきます。
Successfully created record: 001XXXXXXXXXXXXXXX.
以降の例では、このIDを 001XXXXXXXXXXXXXXX として書きます。実際に試すときは、自分の環境で作成されたIDに置き換えてください。
登録したレコードを取得する
作成した取引先をIDで取得します。
sf data get record \
--sobject Account \
--record-id 001XXXXXXXXXXXXXXX \
--target-org my-dev-org
sf data get record は、IDまたは --where による項目条件で単一レコードを取得し、項目と値を表示するコマンドです。
今回のような初心者向けの操作では、まずID指定で試すのが分かりやすいと思います。短縮形を使う場合、--record-id は -i、--where は -w でも指定できます。
取引先レコードを更新する
続いて、登録した取引先に電話番号とWebサイトを設定します。
sf data update record \
--sobject Account \
--record-id 001XXXXXXXXXXXXXXX \
--values "Phone='03-1234-5678' Website='https://example.com'" \
--target-org my-dev-org
sf data update record では、IDまたは --where による項目条件で対象レコードを特定し、指定した項目を更新できます。
--where でも更新できますが、条件に複数レコードが該当した場合は失敗します。入門記事や手順書では、誤更新を避けるためにID指定で進めるのが安全です。
更新後、もう一度取得して値を確認します。
sf data get record \
--sobject Account \
--record-id 001XXXXXXXXXXXXXXX \
--target-org my-dev-org
Salesforceの画面でも確認したい場合は、取引先タブで CLIテスト株式会社 を検索します。スクリーンショットを記事に載せる場合は、ユーザー名、組織ID、アクセストークンなどが写り込まないように注意します。
取引先レコードを削除する
最後に、検証用に作成した取引先を削除します。
sf data delete record \
--sobject Account \
--record-id 001XXXXXXXXXXXXXXX \
--target-org my-dev-org
sf data delete record は、単一レコードを削除するコマンドです。こちらもIDまたは --where による項目条件で対象を指定できます。
通常の削除では、削除されたレコードはごみ箱に入ります。ただし、関連データや業務運用への影響を考えると、本番組織で気軽に試す操作ではありません。必ず検証用データだけを対象にします。
削除されたことを確認したい場合は、同じIDで取得してみます。
sf data get record \
--sobject Account \
--record-id 001XXXXXXXXXXXXXXX \
--target-org my-dev-org
削除済みであれば、対象レコードが取得できない旨のエラーになります。
Salesforce CLIからログアウトする
検証が終わったら、必要に応じてSalesforce CLIに保存されている対象組織の認証を解除します。
sf org logout --target-org my-dev-org
確認なしで実行する場合は --no-prompt を付けます。
sf org logout \
--target-org my-dev-org \
--no-prompt
複数の認証済み組織がある場合でも、--target-org を指定すると対象を明示できます。
--target-org をなるべく書く
この記事のサンプルでは、デフォルト組織を設定したあとでも、各データ操作コマンドに --target-org my-dev-org を付けています。
理由は、複数組織にログインしているときの誤操作を避けたいからです。
個人で試すだけなら省略しても動きます。ただ、記事や手順書として残す場合は、対象組織がコマンド上に見えていたほうが読み手に親切です。
特に create、update、delete のようにデータを変更するコマンドでは、明示しておくほうが安心です。
よくあるエラー
対象組織を指定していない
--target-org を省略すると、デフォルト組織に対して実行されます。
意図した組織か確認するには、次のコマンドを使います。
sf org list
不安な場合は、データ操作コマンドに --target-org my-dev-org を付けます。
オブジェクト名を表示ラベルで書いている
--sobject に指定するのは表示ラベルではなく、API参照名です。
取引先なら 取引先 ではなく Account を指定します。
sf data create record \
--sobject Account \
--values "Name='CLIテスト株式会社'" \
--target-org my-dev-org
カスタムオブジェクトの __c を忘れる
カスタムオブジェクトを扱う場合は、API参照名の末尾に __c が付きます。
例:
--sobject MyObject__c
カスタム項目も同様に MyField__c のようなAPI参照名で指定します。
空白を含む値を引用符で囲んでいない
--values はスペース区切りで複数項目を解釈します。
値に空白がある場合は、値をシングルクォートで囲みます。
--values "Name='CLI Test Company' Industry=Technology"
日本語の会社名でも、記事中ではシングルクォートで囲んでおくと分かりやすいです。
--values "Name='CLIテスト株式会社' Industry=Technology"
必須項目が不足している
sf data create record では、対象オブジェクトの必須項目をすべて指定する必要があります。
標準の取引先では Name が必要です。組織によっては入力規則や必須項目のカスタマイズにより、追加の項目が必要になることもあります。
エラーが出た場合は、Salesforce画面側の必須項目、入力規則、重複ルールなども確認します。
更新・削除対象のIDが違う
--record-id に指定するIDが違うと、意図しないレコードを操作したり、対象が見つからなかったりします。
更新や削除の前に、次のコマンドで対象レコードを確認しておくと安心です。
sf data get record \
--sobject Account \
--record-id 001XXXXXXXXXXXXXXX \
--target-org my-dev-org
まとめ
この記事では、Salesforce CLIの sf コマンドを使って、ログインから取引先レコードの検索・登録・取得・更新・削除・ログアウトまでを一通り試しました。
ポイントは次のとおりです。
-
sf org login webでSalesforce組織へログインできる -
sf org listで接続済み組織を確認できる -
sf data queryでSOQLを実行できる -
sf data create record、get record、update record、delete recordで単一レコードを操作できる - 複数組織にログインしている場合に備えて、
--target-orgを明示すると安心 - 削除コマンドを扱うため、Developer EditionやSandboxなどの検証用組織で試す
- 通常の削除ではごみ箱に入るが、業務組織では復元や影響確認が必要になるため、検証用データだけを対象にする
最初はこのくらいの単一レコード操作に絞ると、Salesforce CLIで何ができるかを掴みやすいと思います。
次に広げるなら、SOSL検索、CSVを使った一括登録・更新、Bulk API 2.0を使った大量データ操作あたりを別記事にすると読みやすそうです。