Salesforce: オブジェクトのクエリ
標準オブジェクトまたはカスタムオブジェクトの1つを、SalesforceのBulk API 2.0を使用してプロジェクトテーブルに読み込みます。Salesforce接続、オブジェクト、フィールドを選択すると、ステップがクエリを構築し、結果セット全体をページングして、各列をSalesforceが宣言する型で取り込みます。クエリを書く必要はありません。
SalesforceにはREST APIを介してクラウド直接で到達するため、このステップにPlaidLinkエージェントは不要です。
| フィールド | 必須 | 備考 |
|---|---|---|
| Salesforce接続 | はい | 読み取りに使用するSalesforce接続です。接続はTools > Connectionsで管理します。 |
| 環境 | いいえ | 接続の環境のうち、どれを読み取るかを指定します。サンドボックス環境はサンドボックス組織を、本番環境は本番を指すようにします。プロジェクト環境(デフォルト)は、プロジェクトの接続環境を使用します。固定環境は、選択した環境を常に使用します。ステップを1つの環境に固定するを参照してください。 |
| オブジェクト | はい | オブジェクトのAPI名です(Account、Opportunity、Invoice__cなど)。ピッカーには、接続のRun Asユーザーがクエリできるオブジェクトが一覧表示され、入力した名前も受け付けるため、検出が利用できない間も、保存済みのステップは引き続き動作します。 |
| ターゲットテーブル | はい | 行を取り込むプロジェクトテーブルです。 |
| 削除済みおよびアーカイブ済みのレコードを含める | いいえ | SalesforceのqueryAllと同様に、ごみ箱内のレコードとアーカイブされたアクティビティも読み取ります。 |
| フィールド | はい | 抽出するフィールドにチェックを入れます。少なくとも1つが必要です。Bulk API 2.0はオブジェクト全体の選択を拒否するため、列の一覧は常に列挙されます。 |
| フィルター | いいえ | Salesforceで抽出を絞り込みます。Salesforceでのフィルターを参照してください。 |
| ウィンドウタグ | いいえ | 抽出ウィンドウに名前を付けます。抽出ウィンドウは1回だけ実行されるを参照してください。 |
Idは、チェックを入れたかどうかにかかわらず常に含まれます。これは、再実行のたびにマージするキーです。通貨フィールドは、オブジェクトにCurrencyIsoCodeがある場合、それも取得します。
ソースタブのプレビューは、ステップが読み取る内容の最大100行を、実行せずに表示します。フィルター内の変数は、実行時と同じ方法で埋め込まれますが、{x:>9}のような変数の書式指定には対応していません。プレビューは、ロックされたプロジェクトでは利用できません。フィルターで、プレビューが読み取り専用かどうかをチェックできないものが使用されている場合は、ステップを実行するよう案内が表示されます。
行の取り込み方法
Section titled “行の取り込み方法”実行のたびに、フィルターの範囲内でオブジェクト全体を読み取り、各ページをIdでターゲットテーブルにマージします。すでにテーブルにある行はその場で置き換えられるため、中断された実行が再開されても、何かが二重に取り込まれることはありません。
取り込まれる列は、データの最初のページから推測した型ではなく、Salesforce自身のフィールドメタデータで宣言された型を使用します。フィールドピッカーの格納名列はその宣言された型であり、フォームで確認した形がそのままテーブルの形になります。
何がどの型で取り込まれるか
Section titled “何がどの型で取り込まれるか”| Salesforceのフィールド型 | 格納名 |
|---|---|
id、reference、string、textarea、phone、url、email、picklist、multipicklist、combobox |
テキスト |
boolean |
ブール値 |
date |
日付 |
datetime |
タイムスタンプ |
time |
時刻 |
int |
整数。フィールドが10桁以上を宣言している場合は64ビット整数 |
double、currency、percent |
数値(広い小数型。38桁で小数点以下10桁) |
この表から、出力を基に構築する前に知っておくべき3つの規則が導かれます。
- 通貨は、通貨型ではなく数値として取り込まれます。 実際の組織では、通貨フィールドのスケールが0、2、3、4で宣言されているため、すべての数値型が、それらすべてに対応できる幅のある1つの小数型で取り込まれます。列に通貨記号はなく、フィールドごとの小数点以下の桁数の制約もありません。オブジェクトに
CurrencyIsoCodeがある場合、その列が通貨フィールドの横に付与されるため、金額は通貨を保持します。単一通貨の組織では、オブジェクトにそのようなフィールドはなく、作成されることもありません。 - パーセントは、Salesforceが報告する整数のままです。
20は0.2ではなく20パーセントを意味します。取り込み時にスケールは変更されません。 - 空の値はNULLとして取り込まれます。 Bulkの結果では、真のnullと明示的な空文字列を区別できないため、テキストを含むすべての列で、どちらも
NULLとして取り込まれます。空文字列の意味を保持する必要がある列には、Salesforce側で数式フィールドが必要です。
ステップが拒否するフィールド
Section titled “ステップが拒否するフィールド”一部のSalesforceフィールド型は、正確に取り込むことができません。そのため、フィールドピッカーはそれらを使用不可としてマークし、実行時に失敗するステップを保存させる代わりに、理由を示します。拒否のたびに、フィールドとそのSalesforceの型が示されます。
| Salesforceのフィールド型 | 理由 | 代わりに行うこと |
|---|---|---|
address、location(複合フィールド) |
複合フィールドには、Bulkクエリで直接読み取れる値がありません。 | 構成要素のフィールドにチェックを入れます。BillingStreet、BillingCity、BillingState、BillingPostalCode、BillingCountry、およびジオロケーションの緯度と経度です。ピッカーには、目の前のフィールドの構成要素が表示されます。 |
base64 |
ファイルとBLOBのコンテンツはインラインで返されません。別途バイナリのダウンロードが必要ですが、このステップでは行いません。 | レコードのほかのフィールドを読み取り、添付ファイルは別途処理します。 |
encryptedstring |
Run AsユーザーにView Encrypted Dataがない場合、Salesforceはエラーではなくマスクされた値を返します。マスクされたデータと実際のデータを区別するものはありません。アスタリスクの行を黙って取り込むより、拒否する方が適切です。 | そのデータをSalesforceの外に出すべきかどうかを慎重に判断してください。このステップで抽出するサポートされた方法はありません。 |
anyType |
実際の型は行ごとに異なる可能性がありますが、テーブルの列には1つの型しかありません。 | 型付きのフィールド、または値をテキストとして表示する数式フィールドを抽出します。 |
| ステップが認識しない型 | テキストとして取り込むと値の意味が黙って変わってしまうため、拒否されます。 | サポートに連絡して、その型のマッピングを追加してもらってください。 |
抽出ウィンドウは1回だけ実行される
Section titled “抽出ウィンドウは1回だけ実行される”ウィンドウタグは、実行が読み込むデータのウィンドウに名前を付けます。期間や、2026-09のようなバッチラベルです。ワークフロー変数を受け付けます。{period}というタグは、ステップが実行されるたびに、その変数の値に解決されます。
抽出ウィンドウは1回だけ実行されます。すでに完了したウィンドウを再実行しても、Salesforceには戻りません。ステップは、再読み取りしなかったことをはっきりと報告し、表示される行数は以前の実行のものであることを伝えます。これは黙って何もしないのではなく、はっきりと何もしない動作であり、すでに取り込んだ結果セットの2つ目のコピーを再実行がページングしてしまうことを防ぐための動作です。
このステップの使い方は3つあります。
- タグを空白のままにして、ステップを1回限りの読み込みとして扱います。最初の実行で読み取り、同じステップの2回目の実行は再生され、再読み取りしなかったことが報告されます。抽出の構築と検証や、1回だけ読み込むテーブルに使用します。
- タグを入力し、次のウィンドウを読み込むときに変更します。
2026-09、次に2026-10のようにします。タグを編集すると新しいウィンドウが始まるため、誰かが手動で進める月次の読み込みは、見た目どおりに動作します。 - ワークフロー変数からタグを作成して、無人の定期取得を行います。たとえば
{period}で、ワークフローの前のステップが、読み込み中の期間に設定したものです。スケジュールされた各実行が独自のウィンドウに名前を付け、同じ期間内の再実行は、別のウィンドウを開始する代わりに、そのウィンドウを再開または再生します。
REST APIまたはMCPの呼び出し元はextract_tagを直接渡し、ウィンドウごとに異なる値を自分で指定します。
中断された実行は同じウィンドウを再開するため、そのウィンドウがまだ完了する必要がある間は、タグを一定に保ってください。タグを変更すると、新しいウィンドウと、Salesforceでの新しいクエリが始まります。フィルターやフィールドを変更するときは、タグも変更してください。すでに実行されたタグの設定を編集すると、競合として拒否されます。
Salesforceでのフィルター
Section titled “Salesforceでのフィルター”オブジェクト全体を取得してからフィルターするのではなく、Salesforceで抽出を絞り込みます。各フィルター条件は、フィールド、演算子、値で構成され、条件はANDで結合されます。値にはワークフロー変数({region}など)を使用できます。
| 演算子 | 備考 |
|---|---|
=、!=、<、<=、>、>= |
入力されたとおりの値と比較されます。 |
LIKE |
ワイルドカードとして%を使用します(例: Acme%)。 |
IN、NOT IN |
値をカンマ区切りのリストで指定します。 |
フィールドと演算子の両方が、クエリが構築される前に、選択したフィールドに対してチェックされます。また、自由形式のWHERE句を書くことはないため、フィルターが抽出の範囲を超えることはありません。チェックを入れたフィールドでフィルターしてください。抽出で選択されていないフィールドを指定したフィルターは拒否されます。
このステップには、行数の上限も並べ替えもありません。Bulk API 2.0は、クエリにどちらかが含まれていると、独自の内部チャンク分割を無効にするため、大きな抽出が遅くなり、タイムアウトしやすくなります。クエリが大きすぎる、または遅すぎる場合の、Salesforce自身の対処法は、選択性の高いフィルター条件です。
ボリュームと変動の適合性
Section titled “ボリュームと変動の適合性”この形(スケジュールに従ってオブジェクト全体を読み取る)は、ボリュームも変動も中程度のオブジェクトに適しています。Accounts、Opportunities、Leads、Campaigns、同程度の規模のカスタムオブジェクトなどです。
Task、EmailMessage、毎日数百万行が変更される大きなカスタムオブジェクトのような、ボリュームも変動も大きいオブジェクトには不向きです。これらを毎晩フルで取得すると、増分同期なら消費しない実時間とAPIの容量を消費します。オブジェクトは大きくても、一部だけが必要な場合は、日付範囲、レコードタイプ、所有者などで抽出を制限するフィルターを使用すると、ボリュームが中程度の取得に戻せます。
実行が完了しない場合
Section titled “実行が完了しない場合”| 表示される内容 | 何が起きたか | 対応 |
|---|---|---|
| 15分後もジョブが実行中であるというエラー | ステップはフォアグラウンドで、Salesforceがクエリを完了するのを待ちます。その待機には上限があります。バックグラウンドでジョブを進めるものはありません。ステップは失敗するため、後続のステップが、この抽出でまだ書き込まれていないテーブルで実行されることはありません。 | ワークフローを再開するか、ステップを再実行します。同じSalesforceジョブで待機を再開し、2つ目のジョブは送信されません。上限を超え続ける場合は、フィルター条件で抽出を絞り込みます。 |
| ウィンドウがすでに完了しており、再読み取りされなかったという警告 | ウィンドウは以前に実行されました。表示される行数は以前の実行のものです。 | 別のウィンドウタグで抽出を実行するか、タグの作成元の変数を進めてください。抽出ウィンドウは1回だけ実行されるを参照してください。 |
| 失敗した、または中止されたジョブを示すエラー | 失敗したBulkクエリジョブは、部分的な結果を生成せず、再開することもできません。ウィンドウはすでに使用済みです。 | 別のウィンドウタグで再実行します。同じウィンドウを再実行すると失敗が再生され、何も送信されません。同じタグでステップの設定を編集すると、競合として拒否されます。 |
| Salesforceのリクエスト上限を示す拒否 | 組織の24時間ローリングのAPIリクエスト許容量が使い果たされました。Salesforceには、そのためのretry-afterは文書化されていません。 | ウィンドウが解除されるのを待ってから再実行します。抽出は引き続き再開可能で、失われたものはありません。 |
| 1つのフィールドとそのSalesforceの型を示す拒否 | そのフィールド型は取り込めないか、Run Asユーザーがそのフィールドを読み取れません。 | ステップが拒否するフィールドと、Run Asユーザーの項目レベルのセキュリティを参照してください。 |
Salesforceは、完了したクエリジョブの結果を7日間取得可能な状態で保持します。これにより、中断された抽出を再開できますが、結果が失われるまでに再開を待てる期間も、これによって制限されます。ジョブは、SalesforceのSetup > Environments > Jobs > Bulk Data Load Jobsで確認できます。
- Salesforceステップ
- Salesforceに接続する — 組織側のセットアップを最初から最後まで説明します
- Salesforce RESTコネクター — 接続フィールドのリファレンス
- ワークフロー内の1つのステップを実行する