概要とビジネスシーン
Salesforce Apex Callouts（Apexコールアウト）は、Salesforceプラットフォームから外部システムへHTTPリクエストを送信し、データ交換を行うための強力な機能です。これにより、SalesforceのCRM機能を拡張し、企業の様々なビジネスプロセスとシームレスに連携することが可能になります。リアルタイムでの情報同期、外部サービスからのデータ取得、またはSalesforceデータの外部公開といった、多様な統合シナリオを実現する上で不可欠な技術です。
実際のビジネスシーン
シーンA：Eコマース業界 - 顧客注文と在庫管理
- ビジネス課題：顧客がオンラインストアで商品を注文した際、Salesforceの商談レコードが作成されるが、実際の在庫情報は外部のERP（Enterprise Resource Planning）システムに保持されており、リアルタイムでの同期ができていない。これにより、在庫切れの商品が注文されたり、手動での在庫確認に時間がかかっていた。
- ソリューション：Apex Callouts を利用して、Salesforceで商談が成立した際に、リアルタイムで外部ERPシステムのAPIを呼び出し、在庫状況を照会。注文処理を進める前に在庫を確認し、在庫引き当てを行う。
- 定量的効果：在庫確認にかかる時間が90%削減され、顧客満足度が向上。在庫切れによる注文キャンセル率が5%低減。
シーンB：金融業界 - 信用スコア照会と不正取引検知
- ビジネス課題：ローン申請者の信用スコアを評価する際、Salesforceに登録された顧客情報だけでは不十分で、外部の信用情報機関のデータベースにアクセスする必要がある。手動での照会は時間がかかり、リアルタイムでの審査が難しい。
- ソリューション：Apex Callouts を使用し、ローン申請レコードが作成・更新された際に、外部の信用情報機関APIを呼び出し、自動的に申請者の信用スコアや過去の金融履歴を取得。取得したデータはSalesforceレコードに反映され、不正取引の可能性を自動で評価するルールエンジンと連携。
- 定量的効果：ローン審査期間が平均3日から1日未満に短縮され、審査業務の効率が50%向上。不正取引検知率が15%向上し、リスク管理が強化。
シーンC：製造業 - IoTデバイスデータと予知保全
- ビジネス課題：工場に設置されたIoTセンサーデバイスからリアルタイムで機械の稼働データ（温度、振動など）が生成されるが、これらのデータがSalesforceのサービスプロセスと連携しておらず、予知保全や異常検知が遅れることがあった。
- ソリューション：IoTプラットフォームが提供するAPIエンドポイントに対し、SalesforceからApex Callouts を用いて定期的にデータを取得、またはIoTプラットフォーム側からSalesforceのAPIへコールアウトを行う。これにより、異常値が検知された際にSalesforce Service Cloudでサービスケースを自動生成し、メンテナンスチームに通知。
- 定量的効果：機器のダウンタイムが20%削減され、メンテナンスコストが10%削減。故障発生前の proactive な対応が可能になり、生産性が向上。
技術原理とアーキテクチャ
Apex Callouts は、Salesforceから外部のWebサービス（REST API、SOAP APIなど）に対してHTTPリクエストを送信し、そのレスポンスを受信するメカニズムを提供します。この機能は主に、HttpRequest、HttpResponse、そしてHttpの各クラスを中心に構築されています。
基礎的な動作メカニズム
Salesforceが外部システムにリクエストを送信する際、まずセキュアな通信経路を確立する必要があります。このため、Salesforceは信頼できる外部エンドポイントのURLを登録する仕組みを提供しています。主要な設定は以下の2つです。
- Remote Site Settings（リモートサイト設定）：特定のドメインへのHTTP/S通信を許可するための設定。最も基本的なセキュリティ要件。
- Named Credentials（名前付き資格情報）：外部システムの認証情報（ユーザー名、パスワード、APIキーなど）をSalesforce内で安全に保存し、Apexコードから簡単に参照できるようにする設定。認証情報のハードコーディングを防ぎ、変更管理を容易にします。また、Salesforceの認証情報プロバイダーを通じてOAuth 2.0などの高度な認証フローをサポートします。
これらの設定後、Apexコード内でHttpRequestオブジェクトを使用してリクエストの内容（エンドポイントURL、メソッド、ヘッダー、ボディ）を定義し、Httpクラスのsend()メソッドで送信します。外部システムからの応答はHttpResponseオブジェクトで受信され、ステータスコード、ヘッダー、ボディなどから処理結果を解析します。
主要コンポーネントと依存関係
- HttpRequestクラス：外部システムへのリクエストを構築するためのクラス。HTTPメソッド（GET, POST, PUT, DELETEなど）、エンドポイントURL、リクエストヘッダー、リクエストボディを設定します。
- HttpResponseクラス：外部システムからのレスポンスを受信するためのクラス。HTTPステータスコード、レスポンスヘッダー、レスポンスボディ（通常はJSONまたはXML）が含まれます。
- Httpクラス：
HttpRequestオブジェクトを外部システムに送信し、HttpResponseオブジェクトを受信するためのユーティリティクラス。send()メソッドが中心的な役割を果たします。 - Remote Site Settings / Named Credentials：上記で説明した通り、セキュリティと認証のために必須の設定です。Named Credentialsを使用すると、Remote Site Settingsを個別に設定する必要がなくなるため、推奨されます。
- JSON / XML Parser：外部システムからのレスポンスボディがJSONまたはXML形式である場合、Apexの組み込みパーサー（
JSON.deserialize,XmlStreamReaderなど）を使用してデータを解析します。
データフロー
| ステップ | 説明 | 主要コンポーネント |
|---|---|---|
| 1. リクエストの構築 | Apexコード内で外部システムへのHTTPリクエスト（URL、メソッド、ボディ、ヘッダー）を定義。 | HttpRequest |
| 2. 認証情報の準備 | Named Credentials または Remote Site Settings を参照し、認証情報を設定。 | Named Credentials / Remote Site Settings |
| 3. リクエストの送信 | 定義されたリクエストを外部システムへ送信。 | Http.send() |
| 4. レスポンスの受信 | 外部システムからの応答をSalesforceが受信。 | HttpResponse |
| 5. レスポンスの解析 | 受信したレスポンスボディ（JSON/XML）をApexで解析し、必要なデータを抽出。 | JSON.deserialize / XmlStreamReader |
| 6. データ処理 | 抽出したデータに基づいてSalesforce内のレコードを作成、更新、または削除。 | Apex DML操作 |
ソリューション比較と選定
Salesforceと外部システムを連携させる方法は複数存在します。ここでは、Apex Calloutsといくつかの関連ソリューションを比較し、適切な選定基準を解説します。
| ソリューション | 適用シーン | パフォーマンス | Governor Limits | 複雑度 |
|---|---|---|---|---|
| Apex Callouts (HttpRequest/Response) |
|
中〜高 (同期は即時、非同期はバックグラウンド) |
|
中〜高 (Apexコードの実装が必要) |
| External Services (登録済みサービス) |
|
中 (内部でApex Calloutsを利用) | Apex Callouts と同等 | 低〜中 (設定ベース、コード記述は少ない) |
| Platform Events (Pub/Subモデル) |
|
高 (非同期、スケーラブル) |
|
低〜中 (イベント定義、ApexまたはフローでPublish/Subscribe) |
| Outbound Message (アウトバウンドメッセージ) |
|
低〜中 (非同期) |
|
低 (設定ベース) |
Apex Callouts を使用すべき場合
- ✅ 外部APIとの間で、複雑な認証スキーム（例：カスタムヘッダー、署名）や特定のHTTPメソッド、ボディ形式が必要な場合。
- ✅ リアルタイムで外部システムとデータを同期し、その結果に基づいてSalesforce内で即座に処理を継続する必要がある場合。
- ✅ 外部APIがOpenAPI/Swaggerの定義ファイルを提供しておらず、宣言的なExternal Servicesでは対応が難しい場合。
- ✅ レスポンスの構造が複雑で、Apexのカスタム解析ロジックが必要な場合。
- ✅ 外部APIとの連携において、非常に細かいエラーハンドリングやリトライロジックを実装したい場合。
- ❌ 外部APIがOpenAPI/Swaggerで完全に定義されており、宣言的に連携できる場合は、External Servicesの利用を検討すべきです。
- ❌ リアルタイム性が不要で、大量のデータを非同期で一方的にプッシュしたい場合は、Platform EventsやOutbound Message、またはBatch Apexと組み合わせたコールアウトを検討すべきです。
実装例
ここでは、Named CredentialsとHttpRequest、HttpResponseクラスを使用して、外部のダミーAPI（JSONPlaceholderを想定）から投稿データを取得するGETリクエストの例と、新しい投稿を作成するPOSTリクエストの例を示します。
前提設定: Named Credential の作成
まず、Salesforceの「設定」から「名前付き資格情報（Named Credentials）」を検索し、「新規名前付き資格情報」を作成します。
- 表示ラベル（Label）: JSONPlaceholder
- 名前（Name）: JSONPlaceholder
- URL:
https://jsonplaceholder.typicode.com - IDタイプ（Identity Type）: Anonymous（この例では認証なしのため）
- プロトコル（Protocol）: HTTPS
- HTTPヘッダーを生成（Generate Authorization Header）: チェックなし
- 残りの設定はデフォルトで保存。
Apexコード例：外部APIから投稿を取得 (GET)
この例では、Named Credential 'JSONPlaceholder' を使用して、/posts/1エンドポイントからIDが1の投稿データを取得します。
public class JsonPlaceholderCalloutService {
// 投稿データを表す内部クラス
public class Post {
public Integer userId;
public Integer id;
public String title;
public String body;
}
/**
* Named Credential を使用して外部APIから投稿を取得する
* @param postId 取得する投稿のID
* @return 取得した投稿オブジェクト、またはnull
*/
@AuraEnabled(cacheable=true) // Lightning Web Component からの呼び出しを想定
public static Post getPostById(Integer postId) {
// Named Credential を指定してリクエストURLを構築。'callout:' プレフィックスが重要。
String endpoint = 'callout:JSONPlaceholder/posts/' + postId;
// HttpRequest オブジェクトを初期化
HttpRequest req = new HttpRequest();
req.setEndpoint(endpoint); // エンドポイントURLを設定
req.setMethod('GET'); // HTTPメソッドをGETに設定
req.setTimeout(120000); // タイムアウトを120秒に設定 (ミリ秒単位)
// Http オブジェクトを作成し、リクエストを送信
Http http = new Http();
HttpResponse res = http.send(req); // コールアウトを実行し、レスポンスを取得
// レスポンスのステータスコードをチェック
if (res.getStatusCode() == 200) { // HTTPステータスコード 200 は成功を示す
// レスポンスボディ (JSON形式) をPostクラスにデシリアライズ
// JSON.deserializeStrict は厳密な型チェックを行うため推奨
return (Post) JSON.deserializeStrict(res.getBody(), Post.class);
} else {
// エラーが発生した場合の処理
System.debug('Callout failed with status code: ' + res.getStatusCode() + ', body: ' + res.getBody());
// エラーを適切にハンドリング (例外をスローするなど)
throw new CalloutException('Failed to retrieve post. Status: ' + res.getStatusCode() + ', Body: ' + res.getBody());
}
}
/**
* Named Credential を使用して外部APIに新しい投稿を作成 (POST)
* @param newPost 作成する新しい投稿オブジェクト (idは不要)
* @return 作成された投稿オブジェクト、またはnull
*/
@AuraEnabled
public static Post createNewPost(String title, String body, Integer userId) {
String endpoint = 'callout:JSONPlaceholder/posts';
HttpRequest req = new HttpRequest();
req.setEndpoint(endpoint);
req.setMethod('POST');
req.setHeader('Content-Type', 'application/json;charset=UTF-8'); // リクエストボディがJSONであることを示すヘッダー
req.setTimeout(120000);
// リクエストボディをJSON形式で準備
// この例では直接Mapを作成していますが、Postオブジェクトをシリアライズすることも可能
Map requestBodyMap = new Map();
requestBodyMap.put('title', title);
requestBodyMap.put('body', body);
requestBodyMap.put('userId', userId);
req.setBody(JSON.serialize(requestBodyMap)); // MapをJSON文字列にシリアライズしてボディに設定
Http http = new Http();
HttpResponse res = http.send(req);
// POSTリクエストの成功ステータスコードは通常 201 Created
if (res.getStatusCode() == 201) {
// 外部APIからのレスポンスは、作成されたリソースの情報を含むことが多い
return (Post) JSON.deserializeStrict(res.getBody(), Post.class);
} else {
System.debug('Callout failed with status code: ' + res.getStatusCode() + ', body: ' + res.getBody());
throw new CalloutException('Failed to create post. Status: ' + res.getStatusCode() + ', Body: ' + res.getBody());
}
}
}
実装ロジック解析：
Postクラスは、外部APIが返すJSONデータの構造に対応するApexの型を定義しています。getPostByIdメソッドは、指定された投稿IDのデータを取得します。callout:NamedCredentialName/path形式でエンドポイントURLを設定します。これにより、Named Credentialによって認証情報とドメインが自動的に処理されます。HttpRequest.setMethod('GET')でHTTP GETメソッドを指定します。Http.send(req)で実際のコールアウトを実行します。HttpResponse.getStatusCode()でHTTPステータスコードを確認し、成功（200 OK）であればHttpResponse.getBody()でJSON文字列を取得します。JSON.deserializeStrict(jsonString, Type.class)を使用して、JSON文字列をApexオブジェクトに変換します。- エラー時には適切な例外をスローし、デバッグログに詳細を出力します。
createNewPostメソッドは、新しい投稿データを外部APIに送信します。HttpRequest.setMethod('POST')でHTTP POSTメソッドを指定します。setHeader('Content-Type', 'application/json;charset=UTF-8')を設定し、リクエストボディがJSON形式であることを示します。- 作成するデータをMapオブジェクトに格納し、
JSON.serialize()でJSON文字列に変換してsetBody()に設定します。 - POSTリクエストの成功ステータスコードは通常201 (Created) です。
注意事項とベストプラクティス
権限要件
- Remote Site Settings（リモートサイト設定）：コールアウト先のURLがここに登録されている必要があります。Named Credentialsを使用する場合は、個別のRemote Site Settingsは不要になります。
- Named Credentials（名前付き資格情報）：Named Credentialsを使用する場合、その特定のNamed Credentialへのアクセス権限がユーザーのプロファイルまたは権限セットに付与されている必要があります。具体的には、「External Credential（外部資格情報）」と「Named Credential Principal（名前付き資格情報プリンシパル）」への参照権限が必要です。
- Apexクラスの実行権限：コールアウトを実行するApexクラスに対する「Apexクラスのアクセス」権限が、ユーザーのプロファイルまたは権限セットに付与されている必要があります。
Governor Limits (2025年最新版に基づく)
Apex Calloutsには、Salesforceプラットフォームの安定性を保つための厳格なGovernor Limitsが適用されます。これらの制限を理解し、遵守することが重要です。
- 同期Apexトランザクションあたりのコールアウト数：最大 100 回
- 各コールアウトの最大タイムアウト：120 秒 (デフォルトは10秒)
- リクエスト/レスポンスボディの最大サイズ：各 6 MB (HTTP GET/HEAD)、12 MB (HTTP POST/PUT)
- 非同期Apex (Future/Queueable) からのコールアウト：Futureメソッドでは一度に1つのコールアウトしか指定できませんが、Queueable Apexでは複数のコールアウトを連鎖させることができます。ただし、1つのトランザクションあたりのコールアウト数100回という制限は変わりません。
- トランザクションあたりのCPU時間：10,000ミリ秒 (同期)、60,000ミリ秒 (非同期)。コールアウト自体はCPU時間としてカウントされませんが、レスポンスの処理やJSONパースはカウントされます。
⚠️ これらの数値はSalesforceの更新によって変更される可能性があります。常に公式ドキュメントで最新の情報を確認してください。
エラー処理
- Try-Catchブロック：コールアウトはネットワークの問題や外部サービスの障害など、様々な理由で失敗する可能性があります。必ず
try-catchブロックでCalloutExceptionを捕捉し、適切にエラーを処理してください。 - HTTPステータスコードの確認：
HttpResponse.getStatusCode()を使用して、外部APIからのHTTPステータスコードを確認し、2xx系の成功コード以外はエラーとして扱います（例: 4xx クライアントエラー、5xx サーバーエラー）。 - 詳細なログ出力：エラー発生時には、リクエストとレスポンスのボディ、ヘッダー、ステータスコードなどをデバッグログに出力し、問題調査を容易にします。機密情報はマスクしてください。
- 再試行メカニズム：一時的なネットワークの問題や外部サービスのタイムアウトに対しては、指数関数的バックオフ（Exponential Backoff）を用いた再試行ロジックを実装することを検討してください。
パフォーマンス最適化
- 非同期処理の活用：ユーザーインターフェースの応答性を保つため、同期コールアウトは最小限に留め、長時間かかる処理やUIをブロックすべきでない処理は
@future(callout=true)メソッドやQueueable Apex、Batch Apexなどの非同期Apexを利用してください。 - 必要最小限のデータ転送：リクエストおよびレスポンスのボディサイズを最小限に抑えるため、本当に必要なデータのみを送信・受信するように設計します。
- レスポンスのキャッシュ：頻繁にアクセスされるが、あまり変化しないデータについては、Salesforceのキャッシュ（例: Platform Cache）やカスタム設定/カスタムメタデータにキャッシュし、外部APIへのコールアウト頻度を減らします。
- Named Credentialsの使用：認証情報の管理を簡素化し、Remote Site Settingsのオーバーヘッドを削減します。また、Salesforceの外部サービス（External Services）との連携も容易になります。
- バルク処理の考慮：一度に大量のデータを連携する場合、外部APIがバルク操作をサポートしていれば、単一のコールアウトで複数のレコードを処理するよう設計します。サポートしていない場合は、Queueable ApexやBatch Apexと組み合わせて、ガバナ制限内で処理を分割します。
よくある質問 FAQ
Q1：Apexコールアウトが失敗する最も一般的な原因は何ですか？
A1：最も一般的な原因は、Remote Site SettingsまたはNamed Credentialsの設定ミス（URLの誤り、認証情報の不一致、アクセス権限の不足）です。次に、ネットワーク接続の問題、外部APIのダウンタイム、HTTPステータスコード2xx以外（例: 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error）が返される外部API側のエラー、ガバナ制限の超過が挙げられます。
Q2：Apexコールアウトのデバッグ方法は？
A2：Developer Consoleでデバッグログを有効にし、「Callout」カテゴリを有効にしてください。ログには、リクエストの送信、レスポンスの受信、および発生したエラーに関する詳細情報が含まれます。特に、System.debug()ステートメントでHttpRequestとHttpResponseオブジェクトのすべてのプロパティ（URL、ヘッダー、ボディ、ステータスコードなど）を出力することで、問題の原因を特定しやすくなります。外部システム側でログを確認することも重要です。
Q3：Apexコールアウトのパフォーマンスを監視するには？
A3：「設定」メニューから「Apex Callouts」ページにアクセスすると、組織全体のApexコールアウトの成功率、失敗率、平均応答時間などの概要を監視できます。より詳細な監視やリアルタイムアラートが必要な場合は、カスタムログオブジェクトを作成してコールアウトの詳細（応答時間、成功/失敗、エラーメッセージ）を記録したり、Salesforce Event Monitoring（イベント監視）や外部のAPM（Application Performance Management）ツールと連携させたりすることを検討してください。
まとめと参考資料
Apex Calloutsは、Salesforceと外部システム間のセキュアで動的なデータ連携を実現するための強力な基盤です。Named Credentialsによる認証管理の簡素化、HttpRequest/HttpResponseクラスによる柔軟なリクエスト構築、そして非同期Apexとの組み合わせによって、様々なビジネス要件に対応できます。Governor Limitsの理解、適切なエラー処理、そしてパフォーマンス最適化のベストプラクティスを適用することで、堅牢でスケーラブルな統合ソリューションを構築することが可能です。Salesforceプラットフォームの可能性を最大限に引き出すために、Apex Calloutsの技術を深く習得することは、Salesforce開発者にとって不可欠なスキルと言えるでしょう。
公式リソース
- 📖 公式ドキュメント：Apex Callouts: Integrations to External Services
- 📖 公式ドキュメント：Callouts to External Services with Named Credentials
- 📖 公式ドキュメント：Apex Governor Limits
- 🎓 Trailhead モジュール：Integrate with External Services
- 🎓 Trailhead モジュール：Apex Integration Services
コメント
コメントを投稿