Salesforce REST API：アーキテクトが解説するシームレスなシステム連携ガイド

背景と応用シナリオ

現代のエンタープライズシステム環境において、データやプロセスのサイロ化は大きな課題です。Salesforce は、単なるCRMプラットフォームに留まらず、企業のあらゆる業務プロセスの中核を担うエコシステムのハブとしての役割がますます重要になっています。このエコシステムを実現する上で不可欠な技術が API (Application Programming Interface、アプリケーションプログラミングインターフェース) であり、その中でも特に REST (Representational State Transfer、具象状態転送) API は、そのシンプルさと Web 標準への準拠から、Salesforce と外部システムを連携させる際の第一選択肢となっています。

Salesforce アーキテクトの視点から見ると、REST API は単なるデータ連携の手段ではありません。それは、スケーラブルで、保守性が高く、セキュアなソリューションを設計するための基本的な構成要素です。適切な API 戦略を立てることは、プロジェクトの成否を左右すると言っても過言ではありません。

応用シナリオ

REST API の具体的な応用シナリオは多岐にわたりますが、アーキテクトとして考慮すべき代表的なパターンは以下の通りです。

リアルタイムデータ同期： 基幹システム (ERP) の顧客マスターデータが更新された際に、即座に Salesforce の取引先 (Account) レコードを更新する。あるいは、Salesforce 上で商談 (Opportunity) が成立した際に、その情報をリアルタイムで外部の受注管理システムに連携する。
カスタムモバイル/Webアプリケーション： Salesforce をバックエンドとして利用し、独自のUI/UXを持つモバイルアプリケーションや顧客向けポータルサイトを構築する。例えば、現場のサービス担当者が使用するモバイルアプリから、Salesforce のケース (Case) や作業指示 (Work Order) を作成・更新する。
Eコマース連携： Eコマースサイトでの商品購入時に、Salesforce の取引先責任者 (Contact)、注文 (Order)、注文商品 (OrderItem) を自動的に作成し、360度の顧客ビューを実現する。
マーケティングオートメーション連携： マーケティングツールで獲得したリード情報を Salesforce のリード (Lead) オブジェクトにリアルタイムで登録し、営業チームへ迅速に引き渡す。

これらのシナリオにおいて、アーキテクトは、単に「繋ぐ」ことだけでなく、パフォーマンス、セキュリティ、将来の拡張性といった非機能要件をいかに満たすかを設計する必要があります。そのために、REST API の原理を深く理解することが不可欠です。

原理説明

Salesforce REST API は、HTTP (Hypertext Transfer Protocol) プロトコルをベースにした、シンプルで軽量な Web サービスです。その設計思想は、Web のアーキテクチャスタイルである REST に基づいています。

REST の基本原則

リソースベース： 全てのデータや機能は「リソース」として扱われ、一意な URI (Uniform Resource Identifier) によって識別されます。例えば、特定の取引先レコードは /services/data/v58.0/sobjects/Account/001xxxxxxxxxxxxxxx のような URI で表現されます。
ステートレス： サーバー側はクライアントのセッション状態を保持しません。各リクエストは、それ自体で完結するために必要な情報をすべて含んでいる必要があります。これにより、サーバー側の実装がシンプルになり、スケーラビリティが向上します。
標準HTTPメソッドの利用： リソースに対する操作は、標準の HTTP メソッド（GET, POST, PATCH, DELETE など）を用いて行います。
- GET： リソースの取得
- POST： 新規リソースの作成
- PATCH： 既存リソースの部分的な更新
- DELETE： リソースの削除

認証と認可：OAuth 2.0

Salesforce API へのアクセスは、業界標準の OAuth 2.0 プロトコルによって保護されています。アーキテクトは、連携シナリオに最適な OAuth フローを選択する必要があります。

Web Server Flow： ユーザーの操作を介して認証を行う、標準的な Web アプリケーション向けのフロー。
JWT Bearer Flow： ユーザーの介在なしに、サーバー間で安全に認証を行うためのフロー。バッチ処理や定期的なデータ同期など、バックエンド連携に最適です。
Username-Password Flow： 非推奨ですが、テストや特定のレガシーシステム連携で使用されることがあります。セキュリティリスクが高いため、慎重な検討が必要です。

認証が成功すると、クライアントはアクセストークンを取得します。以降の API リクエストでは、このアクセストークンを HTTP ヘッダーに含めることで、認証済みユーザーとしてリソースにアクセスできます。

データ形式：JSON

リクエストのボディやレスポンスのデータ形式には、主に JSON (JavaScript Object Notation) が使用されます。JSON は軽量で人間にも読みやすく、多くのプログラミング言語で容易にパースできるため、API 連携のデータ形式として広く採用されています。

Salesforce が提供する REST API の種類

Salesforce は、単一の REST API だけでなく、用途に応じた複数の API を提供しています。アーキテクトは、要件に最も適した API を選択する責任があります。

Standard REST API： 個別の sObject レコードに対する CRUD (Create, Read, Update, Delete) 操作や、SOQL クエリの実行など、基本的な操作を行います。
Composite API： 複数の独立した REST API リクエストを、単一の API コールにまとめることができます。これにより、クライアントとサーバー間のネットワークラウンドトリップを削減し、パフォーマンスを向上させ、API 制限の消費を抑えることができます。トランザクション管理も可能です。
Bulk API 2.0： 数万件以上の大量のレコードを非同期で処理するために設計されています。日次や週次の大規模なデータロードやエクスポートに最適です。
Tooling API： Apex クラスや Visualforce ページなどのメタデータを操作するための API です。CI/CD パイプラインの構築や開発者ツールの作成に使用されます。

これらの API の特性を理解し、適切に使い分けることが、堅牢なシステムアーキテクチャの鍵となります。

示例コード

ここでは、アーキテクトとしてパフォーマンスとトランザクションの観点から特に推奨される Composite API の使用例を見てみましょう。この例では、「新しい取引先 (Account)」と、その取引先に紐づく「新しい取引先責任者 (Contact)」を、1回の API コールで作成します。これにより、ネットワーク遅延を最小限に抑え、処理の原子性を高めることができます。

このコードは Salesforce Developer の公式ドキュメントに基づいています。

Composite API を使用した関連レコードの作成

エンドポイント: POST /services/data/vXX.X/composite

リクエストボディ (JSON):

{
    "allOrNone" : true,
    "compositeRequest" : [{
        "method" : "POST",
        "url" : "/services/data/v58.0/sobjects/Account",
        "referenceId" : "refAccount",
        "body" : {
            "Name" : "Salesforce"
        }
    },{
        "method" : "POST",
        "url" : "/services/data/v58.0/sobjects/Contact",
        "referenceId" : "refContact",
        "body" : {
            "LastName" : "Benioff",
            "AccountId" : "@{refAccount.id}"
        }
    }]
}

コードの詳細な注釈

"allOrNone" : true: このフラグが非常に重要です。true に設定すると、リクエスト内の全てのサブ処理（この場合は取引先の作成と取引先責任者の作成）が成功した場合にのみ、全体のトランザクションがコミットされます。いずれか一つでも失敗した場合、全ての変更がロールバックされます。これにより、データの整合性を保証できます。
"compositeRequest" : [...]: 複数のサブリクエストを格納する配列です。
"method" : "POST": 新しいレコードを作成するため、HTTP POST メソッドを指定します。
"url" : "...": 各サブリクエストが対象とするリソースの URI です。
"referenceId" : "refAccount": このサブリクエストを一意に識別するためのIDです。後のリクエストからこのリクエストの結果を参照するために使用します。
"body" : {...}: 作成するレコードのデータを JSON 形式で指定します。
"AccountId" : "@{refAccount.id}": これが Composite API の強力な機能です。@{referenceId.attribute} という構文を使うことで、同じトランザクション内の先行するサブリクエストの結果（この場合は refAccount という ID で作成された取引先のレコードID）を参照できます。これにより、関連レコードを1回のコールで正しく作成することが可能になります。

注意事項

REST API を利用したシステム連携を設計する際、アーキテクトは以下の点に細心の注意を払う必要があります。

権限 (Permissions)

API 経由でのアクセスは、Salesforce の堅牢なセキュリティモデルに従います。

接続アプリケーション (Connected App): API クライアントは、まず Salesforce 上で接続アプリケーションとして定義される必要があります。ここで、コールバック URL や許可する OAuth スコープ (Scope) を設定します。
OAuth スコープ: api (API アクセス全般)、full (全データへのアクセス)、refresh_token (アクセストークンのリフレッシュ) など、クライアントが必要とする最小限のスコープを付与する最小権限の原則 (Principle of Least Privilege) を遵守することが重要です。
ユーザープロファイルと権限セット: API がどのユーザーとして実行されるかによって、アクセスできるオブジェクトや項目が決定されます。連携専用のユーザーとプロファイルを作成し、必要な CRUD (Create, Read, Update, Delete) 権限や項目レベルセキュリティを厳密に設定することを強く推奨します。

API 制限 (API Limits)

Salesforce はマルチテナント環境であるため、プラットフォーム全体の安定性を維持するために、組織ごとに API コールの回数に制限が設けられています。

API コール数: 24時間あたりの合計 API コール数には上限があります。この制限は Salesforce のエディションやライセンス数によって異なります。
モニタリング: API 制限の消費状況は、「組織情報」ページで確認できるほか、API レスポンスヘッダーの Sforce-Limit-Info からも取得できます。アーキテクトは、この値を監視し、制限に近づいた場合にアラートを発するような仕組みをクライアント側に組み込むことを検討すべきです。
制限への対策:
- 前述の Composite API を使用して、複数のコールを1回にまとめる。
- 大量データの場合は Bulk API 2.0 を使用する。
- 頻繁に変更されないデータは、クライアント側でキャッシュする。
- 不必要なポーリング（定期的な問い合わせ）を避け、Webhook (Outbound Message や Platform Events) などのイベント駆動型アーキテクチャを検討する。

エラー処理 (Error Handling)

堅牢な連携システムは、予期せぬエラーに適切に対処できる必要があります。

HTTP ステータスコード: API は標準的な HTTP ステータスコードを返します（例：200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found）。クライアントはこれらのコードを正しく解釈し、処理を分岐させる必要があります。
エラーレスポンスボディ: 失敗した場合、レスポンスボディには詳細なエラーメッセージ（エラーコードと説明）が JSON 形式で含まれます。これをログに記録し、問題解決に役立てるべきです。
リトライ処理: ネットワークの一時的な問題や、ガバナ制限によるロック競合などでリクエストが失敗することがあります。このような場合には、エクスポネンシャルバックオフ (Exponential Backoff) を伴うリトライロジックを実装することが推奨されます。

まとめとベストプラクティス

Salesforce REST API は、外部システムとの連携を実現するための強力なツールセットです。しかし、その能力を最大限に引き出し、スケーラブルで信頼性の高いソリューションを構築するためには、アーキテクトによる慎重な設計が不可欠です。

以下に、REST API 連携を設計する上でのベストプラクティスをまとめます。

適切な API を選択する: 個別のレコード操作には Standard REST API、複数の操作をまとめるには Composite API、大量データには Bulk API 2.0 と、ユースケースに応じて最適な API を選択します。
セキュリティを最優先する: 常に OAuth 2.0 を使用し、連携シナリオに最適なフロー（サーバー間連携なら JWT Bearer Flow）を選択します。接続アプリケーションのスコープと連携ユーザーの権限は、必要最小限に絞ります。
API 制限を念頭に置いた設計: 設計の初期段階から API コール数を意識します。効率的なデータ取得（必要な項目のみを指定する）、キャッシュ戦略、非同期処理の活用などを検討します。
効率的なデータ操作を心がける: ネットワークラウンドトリップを減らすために Composite API を積極的に活用します。SOQL クエリでは WHERE 句で結果を絞り込み、不要なデータを転送しないようにします。
冪等性 (Idempotency) を確保する: 特にデータを作成・更新する処理において、同じリクエストを複数回送信しても結果が同じになるように設計します（例：外部ID を利用した Upsert 操作）。これにより、リトライ処理を安全に実装できます。
API のバージョン管理を意識する: API の URI にはバージョン番号 (vXX.X) が含まれます。クライアント側でこのバージョンを固定することで、Salesforce のアップデートによる予期せぬ動作変更から連携システムを保護します。定期的に新しいバージョンを確認し、計画的にアップグレードを行うべきです。

これらの原則に従うことで、Salesforce REST API を活用し、ビジネスの要求に応える柔軟かつ堅牢な統合ソリューションを構築することができるでしょう。

にゃんこのSalesforce日記

このブログを検索