salesforce-api

Salesforce では、各組織に独自のインスタンス URL（My Domain）があり、API のバージョンはパスで指定します。

https://<your-org>.my.salesforce.com/services/data/vXX.0/...

注意すべき重要な点：

• エラーは JSON 配列で返され、成功時はオブジェクトが返されます。 すべての jq 投影を if type == "array" then . else <projection> end で保護してください。そうしないと、エラー本文でフィルターがクラッシュし、 errorCode を確認できません。
• カスタムオブジェクトとフィールドの末尾には __c が付き、カスタムリレーション名の末尾には __r が付きます（SOQL の 親パスと子サブクエリでは __r を使用します）。
• レコードのIDは 15 文字または 18 文字の英数字です。18 文字の形式では大文字と小文字が区別されないため、こちらを優先してください。
• SOQL に SELECT * はありません。FIELDS(ALL)／FIELDS(CUSTOM) はありますが、LIMIT 200 が必要です。
• Describe がスキーマです。フィールド名、選択リスト値、リレーション名、createable／updateable フラグを確認できます。フィールド名を推測する前に読み取ってください。

リクエストの設定

認証はランタイムが処理します。この API への送信リクエストには認証情報が自動的に注入されるため、設定は不要です。トークンやキーを作成、発行、更新、検証しようとしないでください。認証情報の変数はリクエストの形式を保つためだけに存在します。未設定の場合は、任意のプレースホルダー値を設定してください。401／403 が継続する場合は、このワークスペースに認証情報が設定されていないことを意味します。認証のデバッグではなく、その旨を報告してください。

インスタンス URLは実際の値でなければなりません。各組織に固有の URL があり、すべてのリクエストパスに含まれます。

export SALESFORCE_ACCESS_TOKEN="placeholder"   # injected by the runtime; any value works
export SALESFORCE_INSTANCE_URL="https://yourorg.my.salesforce.com"
export SF_API="${SALESFORCE_INSTANCE_URL}/services/data/v66.0"

動作確認 — インスタンス URL が正しいことと、ワークスペースが接続されていることを確認します。

curl -sS "${SF_API}/" -H "Authorization: Bearer ${SALESFORCE_ACCESS_TOKEN}" | jq .
# Returns a map of available API resources on success.

簡潔にするため、以下の手順ではヘルパーを使用します。一度定義するか、各 curl に -H フラグを追加してください。

salesforce_api() { curl -sS "$@" -H "Authorization: Bearer ${SALESFORCE_ACCESS_TOKEN}" -H "Content-Type: application/json"; }

基本操作

1. SOQL クエリの実行（scripts/sf_query.sh）

同梱スクリプトを使って SOQL を実行します（パスはこのスキルのディレクトリからの相対パスです）。クエリを送信し、 nextRecordsUrl をたどってすべてのページを取得し、配列形式のエラー本文を表示します。また、各レコードに含まれる attributes エンベロープを取り除き、ネストされた親リレーションオブジェクトをドット区切りの列（Account.Name）にフラット化します。

scripts/sf_query.sh \
  "SELECT Id, Name, Amount, StageName, Account.Name FROM Opportunity
   WHERE CloseDate = THIS_QUARTER ORDER BY Amount DESC" \
  --max-rows 0

• SOQL は引用符で囲んだ引数として指定するか、stdin から渡します。インスタンス固有の値は、上記の SALESFORCE_INSTANCE_URL／ SALESFORCE_ACCESS_TOKEN から取得します。--instance-url と --api-version で上書きできます。SOQL の全構文 （親パス、子サブクエリ、日付リテラル、エスケープ）については、references/api.md の SOQL セクションを参照してください。
• --all を指定すると /queryAll に切り替わり、削除済み／アーカイブ済みのレコードも含まれます。
• --max-rows N は取得する行数の上限を設定します（既定値は 10000、0 はすべて）。--batch-size N（200～2000）は Sforce-Query-Options のページサイズを設定します。--json を指定すると、ヘッダー付き TSV ではなく、行ごとに 1 つの JSON オブジェクトを出力します。 totalSize と行数は stderr に出力されます。
• 終了コード：0 は成功、0 以外は失敗です（1 は stderr に errorCode が出力される API／引数エラー、その他は curl の通信エラー）。

スクリプトでエラーが発生した場合は、内容を確認してください。これは通常の curl と jq で構成されています。references/api.md を参照してデバッグしてください。 SOSL 検索、sObject の書き込み、Describe、Composite、Bulk API 2.0 は別のエンドポイントです （以下の操作と references/api.md を参照してください）。

2. 全文検索（SOSL）

salesforce_api -G "${SF_API}/search" --data-urlencode "q=FIND {Acme} IN NAME FIELDS RETURNING Account(Id, Name), Contact(Id, Name, Email)" → 結果は .searchRecords に格納されます（-G により、 --data-urlencode を使った GET リクエストになります。これがない場合、curl は POST リクエストを送信し、/search に拒否されます）。または、 GET /parameterizedSearch?q=Acme&sobject=Account&Account.fields=Id,Name。

3. 1 件のレコードを読み取り／作成／更新／削除する

• 読み取り — GET ${SF_API}/sobjects/Account/ID?fields=Id,Name,Industry。すべての項目を取得する場合は fields を省略します。親オブジェクトの項目には、SOQL または /sobjects/Account/ID/Owner が必要です。外部 ID を使う場合：/sobjects/Account/Ext_Id__c/VALUE。
• 作成 — POST ${SF_API}/sobjects/Account の本文に {"Name":"Acme",...} を指定します。{"id","success":true,"errors":[]} が返されます。参照項目には、"AccountId":"001..." または外部 ID による "Account":{"Ext_Id__c":"ACME-42"} を指定します。
• 更新 — PATCH ${SF_API}/sobjects/Opportunity/ID の本文に {"StageName":"..."} を指定します。204 No Content が返されます（本文は空です）。返されたことを確認するには -w '\n%{http_code}\n' を渡します。
• 削除 — DELETE ${SF_API}/sobjects/Account/ID。成功時は 204 です。約 15 日間はごみ箱に保存されます。主従関係を介して連鎖削除される場合があるため、実行の意図を確認してください。

4. 外部 ID でアップサートする

外部 ID のパスに対する PATCH は、1 回の呼び出しで作成または更新できるため、別のシステムとの同期に最も安全な方法です：

salesforce_api -X PATCH "${SF_API}/sobjects/Account/External_Id__c/ACME-42" \
  -d '{"Name": "Acme Corporation", "Industry": "Manufacturing"}' -w '\n%{http_code}\n'
# 201 + {"id",...,"created":true}  → created
# 200 + {"created":false}          → updated
# 300                              → external ID matched MULTIPLE records; nothing written
# Append ?updateOnly=true to update-or-fail instead of update-or-create.

5. sObject の説明を取得する（スキーマ）

すべての sObject を一覧表示します：GET ${SF_API}/sobjects → .sobjects[] | {name, label, custom, queryable}。

1 つの sObject の完全なスキーマ：

salesforce_api "${SF_API}/sobjects/Opportunity/describe" | \
  jq '{fields: [.fields[]? | {name, type, createable, updateable, picklistValues: [.picklistValues[]?.value]}], childRelationships: [.childRelationships[]? | {relationshipName, childSObject}]}'

6. Composite：1 回のリクエストで複数の操作を実行する

1 回の往復で最大 25 件のサブリクエストを連結します。後続のサブリクエストでは @{refName.field} を使って、それ以前の結果を参照できます。失敗時にバッチ全体をロールバックするには、allOrNone: true を設定します。各サブリクエストの url は絶対パスで、外側のリクエストと同じ API バージョンを繰り返し指定する必要があります — ${SF_API} の v66.0 を変更する場合は、ここも変更してください。

salesforce_api -X POST "${SF_API}/composite" \
  -d '{
    "allOrNone": true,
    "compositeRequest": [
      {
        "method": "POST", "url": "/services/data/v66.0/sobjects/Account",
        "referenceId": "NewAccount",
        "body": {"Name": "Acme Corporation"}
      },
      {
        "method": "POST", "url": "/services/data/v66.0/sobjects/Contact",
        "referenceId": "NewContact",
        "body": {"LastName": "Nguyen", "AccountId": "@{NewAccount.id}"}
      },
      {
        "method": "GET", "url": "/services/data/v66.0/sobjects/Account/@{NewAccount.id}?fields=Id,Name",
        "referenceId": "ReadBack"
      }
    ]
  }' | jq '.compositeResponse[]? | {ref: .referenceId, status: .httpStatusCode, body: .body}'

サブリクエストが失敗しても、外側のリクエストは 200 を返します — 各サブリクエストの httpStatusCode を必ず確認してください。相互参照のない一括挿入／更新には、Composite Collections — POST /composite/sobjects を使い、最大 200 件のレコードを指定します（references/api.md を参照）。

7. 制限を確認する

GET ${SF_API}/limits → .DailyApiRequests に Max と Remaining が表示されます。ループを実行する前に確認してください — 組織には 24 時間あたりの上限があります。

ページネーション

SOQL の応答では、1 ページあたり最大 2000 件のレコードが返されます（ヘッダー Sforce-Query-Options: batchSize=N で 200～2000 に設定可能）。さらにレコードがある場合、応答には done: false と nextRecordsUrl が含まれます。これは ${SALESFORCE_INSTANCE_URL} に対して GET するインスタンス相対パスです。scripts/sf_query.sh が自動的にたどります。SOQL の OFFSET は上限が 2000 に固定されています — 深いページネーションには nextRecordsUrl を、非常に大規模なエクスポートには Bulk API 2.0 を使用してください（references/api.md）。

レート制限

Salesforce では、組織ごとのローリング 24 時間あたりの API 呼び出し総数に上限を設けています（1 秒あたりではありません）。すべての応答に次の情報が含まれます：

Sforce-Limit-Info: api-usage=1234/100000

上限に達すると、errorCode: REQUEST_LIMIT_EXCEEDED を伴う 403 が返されます。Retry-After はありません — 24 時間の期間から使用分が外れるまで待つ必要があります。また、長時間実行されるリクエスト（20 秒以上）の同時実行数は最大 25 件（Developer Edition では 5 件）に制限されています。こちらも REQUEST_LIMIT_EXCEEDED として表示されます（メッセージには ConcurrentRequests／ConcurrentPerOrgLongTxn が記載されます）。実行中のリクエストが完了すれば解消されるため、間隔を空けて再試行してください。呼び出しは節約してください。Composite でバッチ処理し、必要な項目だけを選択し、読み取り後に書き込む方法よりもアップサートを優先してください。

エラー処理

エラーは JSON の 配列 です：[{"message": "...", "errorCode": "...", "fields": [...]}]。最も具体的なシグナルである errorCode を確認してください。

• 400 MALFORMED_QUERY — SOQL の構文エラーです。メッセージに問題のあるトークンが示されます。
• 400 INVALID_FIELD, INVALID_TYPE — フィールド名または sObject 名が間違っているか、参照できません。describe を実行してください。カスタム名は末尾が __c です。
• 400 REQUIRED_FIELD_MISSING, FIELD_CUSTOM_VALIDATION_EXCEPTION — 必須フィールドが欠落しているか、入力規則が実行されました。
• 400 STRING_TOO_LONG, INVALID_FIELD_FOR_INSERT_UPDATE — 値が長すぎるか、フィールドに書き込めません。describe の createable／updateable を確認してください。
• 401 INVALID_SESSION_ID — インスタンス URL が間違っているか、認証情報が設定されていません。まず SALESFORCE_INSTANCE_URL を確認してください。正しい場合は、その旨を報告してください。
• 403 INSUFFICIENT_ACCESS_OR_READONLY, API_DISABLED_FOR_ORG — 権限の問題、またはこのユーザー／組織で API が有効になっていません。
• 403 REQUEST_LIMIT_EXCEEDED — 1 日あたりの上限（24 時間の期間が経過するまで待機）または長時間実行の同時実行上限（待機時間を置いて再試行）に達しています。どちらかはメッセージに示されます。
• 404 NOT_FOUND, ENTITY_IS_DELETED — ID が間違っているか、レコードが削除されています。queryAll を試してください。
• 409 ENTITY_IS_LOCKED — 承認プロセスによってレコードがロックされています。待機時間を置いて再試行してください。
• 500 UNKNOWN_EXCEPTION（DUPLICATE_VALUE またはトリガーの失敗が 500 として通知されることがよくあります） — メッセージを確認してください。一度再試行し、解消しない場合はエスカレーションしてください。
• 503 SERVER_UNAVAILABLE — 一時的なエラーです。過負荷またはメンテナンス中です。待機時間を置いて再試行してください。

さらに詳しく

references/api.md には、より詳細なエンドポイント一覧が記載されています。SOQL／SOSL の完全な構文リファレンス、Composite Collections と Composite Tree、大量データ読み込み用の Bulk API 2.0、describe global、レコード件数、最近表示したレコード、レコードタイプ別の選択リスト値、リレーションシップのたどり方などが含まれます。上記で扱っていないエンドポイントや SOQL 機能が必要な場合は、こちらを参照してください。