For AI agents: the complete documentation index is available at https://docs.dataplatform.ovh.net/ja/llms.txt, the full documentation bundle is available at https://docs.dataplatform.ovh.net/ja/llms-full.txt, and this page is available as Markdown at https://docs.dataplatform.ovh.net/ja/connectors-sources-salesforce-technical-reference.md.
  • 🇯🇵 日本語

    • 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名の明示的なリスト。空 → describeを介してすべてのクエリ可能なフィールドを発見
    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応答レコード。構造はクエリによって異なります。

    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からの完全なdescribeオブジェクトは深く入れ子になっており、fields、childRelationshipsなどが含まれます。プラットフォームはそれをドット表記の列にフラット化します。

    reports_list

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

    パラメータタイプ必須説明
    max_items数値いいえ返されるレコードの上限
    • API呼び出し: GET /services/data/v60.0/analytics/reports
    • ページネーション: 単一ページ。最大で最初の数百のレポートを返します。
    • 出力: 1レポートごとに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_QUERYSOQL/SOSL 文法エラーです。クエリテキストを確認してください。
    INVALID_TYPEsobject_name は存在しないかアクセスできません。
    INVALID_FIELDfields_filter にリストされているフィールドは Run As ユーザーに表示されません。
    REQUEST_LIMIT_EXCEEDED日次 API クォータに達しました。待つか、オーガニゼーションの割り当てを増やしてください。
    INSUFFICIENT_ACCESSRun As ユーザーにはオブジェクト/フィールドレベルの権限がありません。

    6. 出力形式

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

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

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

    列名は 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 が必要で、他の制限もあります。コネクタはスケールでの予測可能性のために、記述してからクエリするアプローチを好みます。

    さらに深く掘り下げる

    トレーニングや技術的なサポートを必要とする場合は、営業担当者にお問い合わせください、またはプロフェッショナルサービスページを訪れ、見積もりを依頼し、専門家にプロジェクトを分析してもらってください。

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

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

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