Salesforce REST API 徹底解説：統合エンジニアのための実践ガイド

Salesforce 統合エンジニアとして、日々様々なシステム間のデータ連携に携わっています。現代のビジネス環境において、CRM、ERP、マーケティングオートメーション、Eコマースプラットフォームといった各システムがサイロ化せず、シームレスに連携することは企業の競争力を左右する重要な要素です。このシステム連携の核となる技術が API (Application Programming Interface) であり、Salesforce プラットフォームにおいては REST API がその中心的な役割を担っています。

この記事では、統合エンジニアの視点から Salesforce REST API の基本原理、具体的な活用シナリオ、実践的なコード例、そして導入時に必ず押さえておくべき注意事項までを網羅的に解説します。

背景と応用シナリオ

Salesforce REST API は、HTTP プロトコルをベースとした、シンプルで強力な Web サービスです。これにより、外部のアプリケーションやサービスが Salesforce 内のデータに対して、セキュアかつプログラム的にアクセスすることが可能になります。統合エンジニアにとって、これは無限の可能性を秘めたツールキットです。

具体的な応用シナリオとしては、以下のようなものが考えられます。

1. 基幹システム（ERP）との顧客・注文データ同期

企業の基幹システム（例: SAP, Oracle ERP）で管理されている顧客マスターデータや受注情報を、Salesforce の取引先 (Account) や商談 (Opportunity)、注文 (Order) オブジェクトとリアルタイムまたはバッチで同期します。これにより、営業部門とバックオフィス部門が常に最新の情報を共有できます。

2. Eコマースサイトとの連携

オンラインストアで新規顧客登録や商品購入が行われた際、REST API を呼び出して Salesforce にリード (Lead) や取引先責任者 (Contact)、そして商談を自動的に作成します。これにより、マーケティングや営業へのスムーズな情報連携が実現します。

3. カスタムモバイルアプリケーションの開発

自社独自のモバイルアプリケーションを開発し、そのバックエンドとして Salesforce を利用するケースです。アプリケーションは REST API を通じて Salesforce のデータを読み書きし、ユーザーにリッチな体験を提供します。

4. Web フォームからのリード自動登録

企業のウェブサイトに設置された「お問い合わせフォーム」や「資料請求フォーム」から送信された情報を、サーバーサイドのプログラムが受け取り、Salesforce の REST API を経由してリードオブジェクトに直接登録します。

原理説明

Salesforce REST API の仕組みを理解するためには、いくつかの重要な概念を把握する必要があります。

REST (REpresentational State Transfer) の原則

REST は、Web サービスの設計思想の一つです。その中心には以下の概念があります。

リソース (Resource): Salesforce 上のすべてのデータ（取引先、取引先責任者、カスタムオブジェクトのレコードなど）は、一意の URI (Uniform Resource Identifier) を持つ「リソース」として表現されます。

HTTP メソッド (HTTP Verbs):

GET: リソースの取得
POST: 新規リソースの作成
PATCH: 既存リソースの部分的な更新
DELETE: リソースの削除

ステートレス (Stateless): 各リクエストは、それ自体で完結しており、サーバー側はクライアントの状態を保持しません。すべての必要な情報はリクエストに含まれている必要があります。

認証フロー: OAuth 2.0

Salesforce の API にアクセスするには、まず認証を行い、アクセストークン (Access Token) を取得する必要があります。Salesforce では、業界標準の OAuth 2.0 (Open Authorization 2.0) プロトコルが採用されています。

統合シナリオで一般的に利用されるのは「JWT Bearer Flow」や「Username-Password Flow」ですが、基本的な流れは以下の通りです。

接続アプリケーション (Connected App) の作成: Salesforce 組織内で、外部アプリケーションからの接続を許可するための「接続アプリケーション」を設定します。これにより、コンシューマキー (Consumer Key) とコンシューマシークレット (Consumer Secret) が発行されます。
アクセストークンの要求: 接続アプリケーションの情報とユーザーの認証情報（フローによる）を使用して、Salesforce の認証エンドポイントにリクエストを送信します。
アクセストークンの取得: 認証が成功すると、Salesforce はアクセストークンとインスタンス URL を返却します。このアクセストークンが、以降の API リクエストにおける「通行手形」となります。

アクセストークンを取得した後は、すべての API リクエストの HTTP ヘッダーにこのトークンを含めることで、Salesforce へのアクセスが許可されます。

Authorization: Bearer 00D....!....

示例代码

ここでは、最も基本的な操作である「新しい取引先レコードの作成」と、Salesforce 側でカスタム API を公開する方法の2つの例を、Salesforce 公式ドキュメントに基づいて紹介します。

外部システムから Salesforce へレコードを作成する (cURL)

これは、外部のサーバーやアプリケーションから Salesforce REST API を呼び出す際の最も一般的な例です。以下の cURL コマンドは、`MyDomainName.my.salesforce.com` というインスタンスに存在する Salesforce 組織に対して、"Express Logistics and Transport" という名前の新しい取引先レコードを作成します。

詳細な注釈:

-X POST: HTTP メソッドとして POST を指定し、リソースの作成を指示します。
-H "Authorization: Bearer ...": 認証フローで取得したアクセストークンを Bearer トークンとして Authorization ヘッダーに設定します。
-H "Content-Type: application/json": リクエストボディの形式が JSON であることを示します。
-d '{"Name" : "Express Logistics and Transport"}': 実際に送信するデータ（リクエストボディ）です。JSON 形式で、作成したいレコードの項目 (API 参照名) と値を指定します。
URL: `https://MyDomainName.my.salesforce.com/services/data/v58.0/sobjects/Account/` がエンドポイントです。`v58.0` は API バージョン、`sobjects/Account` は操作対象のリソース（取引先オブジェクト）を示します。

curl https://MyDomainName.my.salesforce.com/services/data/v58.0/sobjects/Account/ -X POST -H "Authorization: Bearer 00D....!..." -H "Content-Type: application/json" -d '{"Name" : "Express Logistics and Transport"}'

成功すると、Salesforce は HTTP ステータスコード `201 Created` と共に、作成されたレコードの ID を含む JSON レスポンスを返します。

{
    "id" : "001xx000003DHP0AAO",
    "success" : true,
    "errors" : []
}

Apex をカスタム REST APIとして公開する

逆に、Salesforce 側で独自のビジネスロジックを持つカスタム API を作成し、外部システムから呼び出させることも可能です。これは `@RestResource` アノテーションを付与した Apex クラスを作成することで実現します。

詳細な注釈:

@RestResource(urlMapping='/Cases/*'): このクラスが REST リソースであることを宣言します。`urlMapping` は、この API のエンドポイントのパスを定義します。`*` はワイルドカードで、URL の一部をパラメータとして受け取ることができます。
@HttpGet: このメソッドが HTTP GET リクエストに応答することを示します。同様に `@HttpPost`, `@HttpPatch`, `@HttpDelete` などがあります。

RestRequest req = RestContext.request;:

String caseId = req.requestURI.substring(req.requestURI.lastIndexOf('/')+1);:

return [SELECT CaseNumber, Status, Origin FROM Case WHERE Id = :caseId];:

@RestResource(urlMapping='/Cases/*')
global with sharing class CaseManager {

    @HttpGet
    global static Case getCaseById() {
        RestRequest req = RestContext.request;
        // Grab the caseId from the end of the URL
        String caseId = req.requestURI.substring(req.requestURI.lastIndexOf('/')+1);
        Case result =  [SELECT CaseNumber, Status, Origin FROM Case WHERE Id = :caseId];
        return result;
    }
}

この Apex クラスをデプロイすると、外部システムは `https://MyDomainName.my.salesforce.com/services/apexrest/Cases/{ケースID}` というエンドポイントに対して GET リクエストを送信することで、特定のケース情報を取得できるようになります。

注意事項

Salesforce REST API を利用した統合を設計・実装する際には、以下の点に十分注意する必要があります。

認証と権限 (Authentication & Permissions)

API 経由での操作は、すべて認証されたユーザーの権限に基づいて実行されます。つまり、API を使用するユーザーが特定のオブジェクトや項目へのアクセス権（プロファイルや権限セットで定義）を持っていなければ、API 経由でもそのデータにアクセスすることはできません。オブジェクトレベルセキュリティ、項目レベルセキュリティ、共有ルールがすべて適用されることを念頭に置いてください。

API 制限 (API Limits)

Salesforce は、プラットフォーム全体のパフォーマンスと安定性を維持するために、各組織が24時間以内に実行できる API コール数に上限を設けています。これは「API Request Limits (APIリクエスト制限)」と呼ばれ、Salesforce のエディションやライセンス数によって異なります。設計段階で、連携によって発生する API コール数を試算し、上限を超えないように注意する必要があります。大量のデータを扱う場合は、1回の API コールで複数のレコードを処理できる Bulk API や Composite API の利用を検討してください。自組織の制限は、[設定] > [組織情報] で確認できます。

エラー処理 (Error Handling)

API 連携は必ずしも常に成功するとは限りません。ネットワークの問題、認証情報の失効、入力データのバリデーションエラー、Salesforce 側のトリガーやフローによるエラーなど、失敗する要因は様々です。クライアントアプリケーション側では、Salesforce から返される HTTP ステータスコード（例: 400 Bad Request, 401 Unauthorized, 403 Forbidden）と、レスポンスボディに含まれるエラーメッセージを適切に解釈し、ログ記録やリトライ処理を行う堅牢なエラーハンドリング機構を実装することが不可欠です。

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

Salesforce REST API は、外部システムと Salesforce を連携させるための強力で標準的な手段です。その仕組みは HTTP と JSON をベースにしているため、多くの開発者にとって学習コストが低く、幅広いプラットフォームや言語から利用できるという利点があります。

統合エンジニアとして成功するためには、単に API を呼び出す方法を知っているだけでなく、プラットフォームの制約を理解し、パフォーマンスと拡張性に優れた設計を行うことが求められます。以下に、実践的なベストプラクティスを挙げます。

常に最新の安定 API バージョンを利用する: Salesforce は年に3回バージョンアップします。新しいバージョンでは機能が追加されたりパフォーマンスが改善されたりすることがあるため、可能な限り最新の API バージョン（例: v58.0）を指定して利用しましょう。
Composite API を活用してリクエストをまとめる: 関連する複数の操作（例: 取引先を作成し、次に関連する取引先責任者を複数作成する）を行う場合、個別の API コールを何度も行うのではなく、Composite API を使って1回のリクエストにまとめることで、API コール数を削減し、パフォーマンスを向上させることができます。
アクセストークンを安全に管理する: アクセストークンやリフレッシュトークンは、絶対にクライアント側のコードにハードコーディングしてはいけません。サーバーサイドの安全な場所に保管し、必要に応じてリフレッシュトークンを使って新しいアクセストークンを再取得するロジックを実装してください。
冪等性（Idempotency）を考慮する: ネットワークエラーなどでリトライ処理を行う場合、同じリクエストが複数回実行されても結果が変わらないように設計することが重要です。例えば、重複を防ぐために外部 ID (External ID) を活用するなどの工夫が考えられます。
API 制限の監視: 定期的に API の使用状況を監視し、予期せぬ急増や上限への接近がないかを確認する仕組みを導入しましょう。

これらの原理とベストプラクティスを深く理解し、実践することで、Salesforce をハブとした堅牢でスケーラブルな統合ソリューションを構築することができるでしょう。

にゃんこのSalesforce日記

このブログを検索