Salesforce: 技術リファレンス

これは、主な Salesforce コネクタのドキュメントの技術的な補助資料です

Objective

これは、主な Salesforce コネクタドキュメントの技術的な補助資料です。認証の内部、エンドポイントの動作、ページネーション、レート制限、出力形式など、データパイプラインにコネクタを統合するために必要なすべての内容をカバーしています。

1. 認証: OAuth 2.0 クライアント資格情報フロー

フロー

コネクタは、各実行の開始時に、3つの資格情報を短期間有効なアクセストークンと交換します:

POST <instance_url>/services/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<Consumer Key>
&client_secret=<Consumer Secret>

Salesforce は、access_token、標準的な instance_url、および token_type: Bearer を返します。コネクタは、その後、すべての後続のリクエストで Authorization: Bearer <token> を使用します。

トークンは更新されません

クライアント資格情報フローは、リフレッシュトークンを発行しません。コネクタは、各抽出実行で新しいトークンをリクエストします。これは、Salesforce のデフォルトのアクセストークンの有効期限（約2時間、ご自身の組織で設定された値については公式ドキュメントを参照してください）内に収まります。

インスタンスURLの解決

コネクタ設定に入力したどのインスタンスURLでも、トークン応答は組織の標準的なURLを返します。コネクタは、すべてのREST呼び出しで応答値を使用するため、https://mycompany.my.salesforce.com または https://mycompany.develop.my.salesforce.com のいずれを提供しても問題ありません。

必要なOAuthスコープ

最低限: Manage user data via APIs (api)。データ抽出には、他のスコープは必要ありません。OAuthトークンとスコープの公式ドキュメントを参照してください。

2. アーキテクチャ

半構造化パターン。 各エンドポイントは生のJSON（辞書のリスト）を返します。プラットフォームは入れ子になったフィールドをフラット化（ドット表記）し、スキーマを自動的に推測します。列をどこかで宣言する必要はありません。
ハイブリッドエンドポイントごとの設計。 データエンドポイント（sobject_records、soql_query、sosl_search）は、共有SOQLページネーションヘルパーを介してルーティングされます。メタデータエンドポイント（sobjects_list、sobject_describe、reports_list、limits）は、それぞれ専用のRESTリソースを呼び出します。
デフォルトフィールドの説明→クエリ。 sobject_records が fields_filter なしで使用される場合、コネクタはまずsObjectの説明を取得してすべてのクエリ可能なフィールド名を収集し、その後それらを明示的にリストするSOQL SELECT を構築します。Salesforce SOQLには SELECT * がありません: 明示的なフィールドは常に必要です。
入力の正規化。 SOQL/SOSL入力は、先頭/末尾の空白と任意の末尾の ; （Salesforceはステートメント区切り文字を使用しません）が削除されます。where_clause フィールドは、先頭に WHERE キーワードがあるかないかの入力を受け付けます。コネクタは、存在する場合はそれを削除し、その後独自のものをプレフィックスとして追加します。

3. エンドポイントリファレンス

すべてのデータエンドポイントは、JSONオブジェクトのリストを返します。/query からの各オブジェクトには、attributes サブ辞書（{"type": "<sObject>", "url": "/services/data/v60.0/sobjects/<sObject>/<Id>"}）が、要求されたフィールドとともに含まれます。

sobject_records

SOQLを介して標準またはカスタムsObjectからレコードを抽出します。

パラメータ	タイプ	必須	説明
`sobject_name`	テキスト	はい	sObjectのAPI名（例: `Account`、`Contact`、`MyObject__c`）
`fields_filter`	タグ	いいえ	フィールドAPI名の明示的なリスト。空 → 説明を介してすべてのクエリ可能なフィールドを発見
`where_clause`	テキストエリア	いいえ	SOQL WHERE式、`WHERE` キーワードなし（オプション、先頭の `WHERE` は削除されます）
`max_items`	数値	いいえ	返されるレコードの上限

API呼び出し: GET /services/data/v60.0/query?q=SELECT <fields> FROM <sobject_name> [WHERE <where_clause>]
ページネーション: SOQL nextRecordsUrl （カーソルベース、セクション4を参照）
出力: 生のSOQL応答レコード。

soql_query

高度なユースケース（サブクエリ、集計、ジョイン）のためのフリーフォームSOQL。

パラメータ	タイプ	必須	説明
`soql`	テキストエリア	はい	SOQLステートメント。複数行サポート
`max_items`	数値	いいえ	返されるレコードの上限

API呼び出し: GET /services/data/v60.0/query?q=<soql>
ページネーション: SOQL nextRecordsUrl
出力: 生のSOQL応答レコード。構造はクエリによって異なります。

sosl_search

Salesforce Object Search Language: 複数のsObjectを横断するフルテキスト検索。

パラメータ	タイプ	必須	説明
`sosl`	テキストエリア	はい	SOSLステートメント（例: `FIND {Acme} IN NAME FIELDS RETURNING Account(Id, Name)`）
`max_items`	数値	いいえ	返されるレコードの上限

API呼び出し: GET /services/data/v60.0/search?q=<sosl>
ページネーション: 単一ページ。SOSLは、通常サーバーサイドで2000レコードに制限された結果セットを返します。
出力: searchRecords の各レコードには、そのsObjectを識別する attributes.type フィールドが含まれます。

sobjects_list

Run Asユーザーに利用可能なsObjectのフルカタログ。

パラメータ	タイプ	必須	説明
`max_items`	数値	いいえ	返されるレコードの上限

API呼び出し: GET /services/data/v60.0/sobjects
ページネーション: 単一ページ。
出力: メタデータ（name、label、custom、queryable、createableなど）を持つsObjectごとに1レコード。

sobject_describe

1つのsObjectのフルスキーマ（フィールド、タイプ、関係、ピックリスト値）。

パラメータ	タイプ	必須	説明
`sobject_name`	テキスト	はい	sObjectのAPI名

API呼び出し: GET /services/data/v60.0/sobjects/<name>/describe
ページネーション: 1レコードが返されます（1行テーブル）。
出力: Salesforceからの完全な説明オブジェクトは、深く入れ子になっており、fields、childRelationshipsなどを含みます。プラットフォームはそれをドット表記の列にフラット化します。

reports_list

組織に保存されているレポートのリスト。

パラメータ	タイプ	必須	説明
`max_items`	数値	いいえ	返されるレコードの上限

API呼び出し: GET /services/data/v60.0/analytics/reports
ページネーション: 単一ページ。最大で最初の数百のレポートを返します。
出力: レポートごとに1レコード（Id、Name、DeveloperName、FolderNameなど）。レポート自体は実行されません。

limits

組織レベルのAPI使用量とクォータ。

API呼び出し: GET /services/data/v60.0/limits
ページネーション: 単一ページ（ペイロードは、数十の制限を説明する1つのJSONオブジェクトです）。
出力: コネクタは応答を名前付き制限ごとに1レコードのリストに再形成し、元のキー（Max、Remaining）を保持します。

4. ページネーション

SOQLベースのエンドポイント（sobject_records、soql_query）は、Salesforceのカーソルベースのページネーションを使用します:

初期応答には totalSize、done: false、records、および nextRecordsUrl （/services/data/v60.0/query/01g...-2000 のようなパス）が含まれます。
コネクタは nextRecordsUrl をフォローし、done: true または max_items に達するまで続けます。
デフォルトのページサイズは2000レコード（サーバーサイドのデフォルト）です。

非SOQLエンドポイント（sosl_search、sobjects_list、sobject_describe、reports_list、limits）は、このバージョンではページネーションを行いません。

5. レート制限とエラーハンドリング

Salesforce の制限

日次 API リクエスト: オーガニゼーション全体のソフトクォータ、エディションによって異なります（例: Enterprise ベースでは 100,000/日、Unlimited ではより高く、Developer Edition では寛大です）。limits エンドポイントで、自分のオーガニゼーションの正確な現在の値を確認してください。
同時呼び出し: Developer Edition では 5、Enterprise+ では 25 です。各リクエストはサーバーサイドで 10 分間タイムアウトします。

現在の数値については、API リクエスト制限と割り当てをご覧ください。

コネクタが行うこと

HTTP 429: Salesforce REST では稀ですが、処理されます。コネクタは Retry-After ヘッダーを尊重し、同じリクエストを再試行します。
HTTP 4xx その他: Salesforce エラーメッセージをログに表示して、即座に抽出失敗として通知します。コネクタは権限エラーをキャッチしません。Run As ユーザーがフィールドや sObject を見ることができない場合、抽出は失敗し、エラーが表示されます。
HTTP 5xx: 4xx と同様に、即座に通知されます。一時的なサーバーエラーは手動で再実行する必要があります。

一般的な Salesforce エラーコード

エラーコード	意味
`INVALID_SESSION_ID`	アクセストークンが期限切れです。新しいトークンを取得するために再実行してください。
`MALFORMED_QUERY`	SOQL/SOSL 文法エラーです。クエリテキストを確認してください。
`INVALID_TYPE`	`sobject_name` が存在しないかアクセスできません。
`INVALID_FIELD`	`fields_filter` にリストされたフィールドが Run As ユーザーに表示されません。
`REQUEST_LIMIT_EXCEEDED`	日次 API クォータに達しました。待つか、オーガニゼーションの割り当てを増やしてください。
`INSUFFICIENT_ACCESS`	Run As ユーザーにオブジェクト/フィールドレベルの権限がありません。

6. 出力形式

すべてのエンドポイントは生の JSON を返します。プラットフォームは自動的に:

ネストされた辞書をドット記法の列にフラット化します（例: attributes.type, attributes.url）。
スキーマを最初のバッチから推測し、後続のバッチで新しいフィールドが導入された場合に拡張します。
レイクハウスに結果をデータセットとして保存し、クエリ可能なテーブルとして格納します。

sobject_records と soql_query の場合、各レコードには選択したフィールドと attributes サブオブジェクトが含まれます。メタデータエンドポイント（sobject_describe, sobjects_list, limits）の場合、ペイロードは API レスポンスを 1 つ以上のレコードにリシェイプしたものです。

列名は Salesforce の API フィールドの大文字小文字を反映します（標準: Id, Name, CreatedDate）。カスタムフィールドは、与えた大文字小文字を保持します（例: MyField__c）。

7. 制限事項

Salesforce REST API v60.0 はハードコードされています。新しいバージョン（Spring '26 は v66.0）は、専用のエンドポイントとして公開されていない機能を追加します。これらは soql_query を使用して、クエリ可能なものはすべてアクセス可能です。
書き込み操作はサポートされていません（作成/更新/削除はできません）。
Bulk API 2.0 はサポートされていません: Salesforce REST クエリはページネーションされていますが、複数百万行の抽出には Bulk よりも非効率です。
ストリーミング / プラットフォームイベント / Pub/Sub API はサポートされていません: バッチのみのコネクタです。
レポートはリストされますが、実行されません。このバージョンでは /analytics/reports/<id>/executeAsync を使用したレポートの実行は対象外です。
複合フィールド（address, location）はデフォルトのフィールド発見から除外されます。fields_filter が空の場合、コネクタはこれらのタイプをスキップします。サブフィールドクエリが必要なためです。明示的な fields_filter（例: BillingStreet, BillingCity, BillingCountry）を使用して、サブフィールドを抽出します。
SOQL FIELDS(ALL) は使用されません。Salesforce の FIELDS(ALL) 文法には LIMIT 200 が必要で、他の制限もあります。コネクタはスケール可能性を考慮して、describe-then-query アプローチを好みます。

さらに詳しく

当社のソリューションを実装するためのトレーニングや技術サポートが必要な場合は、営業担当者にお問い合わせください、またはこのリンクをクリックして、プロフェッショナルサービスの専門家に見積もりを依頼し、プロジェクトのカスタム分析を依頼してください。

質問をする、フィードバックを送る、Data Platform を構築するチームと直接交流するには、専用の Discord チャネルにアクセスしてください。

OVHcloud サービスについてサポートが必要な場合は、ヘルプセンターでリクエストを作成してください。

ユーザーコミュニティに参加してください。

Salesforce: 技術リファレンス#

#Objective

#1. 認証: OAuth 2.0 クライアント資格情報フロー

#フロー

#トークンは更新されません

#インスタンスURLの解決

#必要なOAuthスコープ

#2. アーキテクチャ

#3. エンドポイントリファレンス

#sobject_records

#soql_query

#sosl_search

#sobjects_list

#sobject_describe

#reports_list

#limits

#4. ページネーション

#5. レート制限とエラーハンドリング

#Salesforce の制限

#コネクタが行うこと

#一般的な Salesforce エラーコード

#6. 出力形式

#7. 制限事項

#さらに詳しく