背景と適用シナリオ
Salesforce 開発者として、私たちは日々、外部システムとの連携という課題に直面しています。顧客情報を豊かにするためのデータエンリッチメント、リアルタイムでの在庫確認、外部のメッセージングプラットフォームへの通知など、Salesforce の能力を最大限に引き出すためには、外部の API (Application Programming Interface) との連携が不可欠です。
従来、このような連携を実現するための主要な方法は、Apex コードを使用して HTTP コールアウトを実装することでした。このアプローチは非常に柔軟性が高い一方で、以下のような開発者にとっての課題も伴います。
- 開発工数：HTTP リクエストの作成、レスポンスの解析 (JSON/XML のデシリアライズ)、認証処理など、定型的ながらも時間のかかるコーディングが必要です。
- テストコード：Salesforce のガバナ制限を満たすため、モックを使用したコールアウトのテストクラスを記述する必要があり、これもまた工数を増加させます。
- メンテナンス性：API の仕様変更があった場合、Apex コードの修正、テスト、そしてデプロイが必要となり、迅速な対応が難しい場合があります。
- スキルセットの要求：Apex 開発の知識がない管理者やコンサルタントにとっては、API 連携は大きな障壁でした。
これらの課題を解決するために Salesforce が提供する強力なツールが、External Services (外部サービス) です。External Services は、REST ベースの API 仕様を Salesforce に登録するだけで、その API を呼び出すためのinvocable action (呼び出し可能なアクション) を自動的に生成する宣言的なフレームワークです。これにより、開発者は一行の Apex コードも書くことなく、Flow や Einstein ボットなどのノーコード・ローコードツールから直接外部 API を呼び出すことが可能になります。
具体的な適用シナリオとしては、以下のようなケースが考えられます。
- 住所の正規化：取引先責任者の住所が入力された際に、外部の住所検証 API を Flow から呼び出し、郵便番号の自動入力や表記揺れの修正を行う。
- 金融情報取得：商談が特定のフェーズに達した際に、外部の金融 API を呼び出して最新の株価や為替レートを取得し、商談レコードに記録する。
- プロジェクト管理ツール連携：ケースがクローズされた際に、Asana や Jira の API を呼び出して、関連タスクを自動的に完了させる。
- Slack/Teams 通知：重要なレコード (例えば、金額の大きい商談) が作成された際に、Flow から Slack API を叩いて指定のチャンネルに即時通知を送る。
このように、External Services は、開発者にとっては定型的なコールアウト実装の工数を削減し、管理者にとってはこれまで開発者に依頼するしかなかった API 連携を自らの手で実現可能にする、画期的な機能です。
原理説明
External Services の魔法のような機能は、API の「設計図」とも言えるスキーマ定義に基づいて成り立っています。その中心的な役割を担うのが OpenAPI 仕様です。
OpenAPI (旧 Swagger) は、REST API を記述するための標準的な仕様です。この仕様に準拠した JSON または YAML 形式のファイルには、API のエンドポイント、利用可能な HTTP メソッド (GET, POST, PUT, DELETE など)、各操作で要求されるパラメータ、そして返されるレスポンスのデータ構造などが詳細に定義されています。
External Services の動作プロセスは、以下のステップで構成されます。
- スキーマの提供：開発者または管理者は、連携したい外部 API の OpenAPI 2.0 または 3.0 仕様に準拠したスキーマファイルを用意します。
- 外部サービスの登録：Salesforce の [設定] メニューから [外部サービス] に移動し、用意したスキーマファイルをアップロードします。この際、API の認証情報を安全に管理するための Named Credential (指定ログイン情報) を関連付けます。
- アクションの自動生成：Salesforce はアップロードされたスキーマを解析します。スキーマ内で定義されている各 API 操作 (例: `POST /users`, `GET /accounts/{id}`) に対応する invocable action をバックグラウンドで自動的に生成します。内部的には、Salesforce が動的に Apex クラスとメソッドを生成していますが、私たちはそれを意識する必要はありません。
- 宣言的ツールでの利用：生成されたアクションは、Flow Builder の [アクション] 要素や、Einstein ボットのダイアログなどから、標準のアクションと同様に呼び出すことができるようになります。スキーマで定義された入力パラメータは Flow の変数として渡し、API からのレスポンスは出力変数として受け取ることができます。
このプロセスの鍵となるのが Named Credential です。Named Credential は、API のエンドポイント URL と認証情報を一元管理するための仕組みです。API キーを URL に含める、HTTP ヘッダーに認証トークンを設定する、OAuth 2.0 フローで認証するなど、様々な認証方式をサポートしています。コードや Flow の定義内に直接認証情報をハードコーディングする必要がなくなるため、セキュリティが向上し、サンドボックスから本番環境への移行もスムーズになります（各環境で Named Credential の設定を切り替えるだけ）。
結果として、開発者は API の複雑な仕様や認証の詳細を抽象化し、ビジネスロジックの実装に集中することができるのです。
示例代码 (OpenAPI 2.0 スキーマ)
External Services の核心は OpenAPI スキーマです。ここでは、Salesforce 公式ドキュメントでよく使用される、2つの数値を加算する非常にシンプルな電卓サービスの API スキーマを例として示します。この JSON ファイルを Salesforce に登録することで、「add」という名前のアクションが Flow で利用可能になります。
{
"swagger": "2.0",
"info": {
"title": "Calculator Service",
"description": "A simple service to perform calculations.",
"version": "1.0"
},
"host": "my-calculator-service.com",
"schemes": [
"https"
],
"paths": {
"/add": {
"post": {
"summary": "Add two numbers",
"description": "Takes two numbers (n1 and n2) and returns their sum.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "body",
"description": "The numbers to be added.",
"required": true,
"schema": {
"$ref": "#/definitions/AddRequest"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"schema": {
"$ref": "#/definitions/AddResponse"
}
}
}
}
}
},
"definitions": {
"AddRequest": {
"type": "object",
"properties": {
"n1": {
"type": "number",
"description": "First number"
},
"n2": {
"type": "number",
"description": "Second number"
}
}
},
"AddResponse": {
"type": "object",
"properties": {
"result": {
"type": "number",
"description": "The sum of n1 and n2"
}
}
}
}
}
スキーマの解説
"swagger": "2.0": このスキーマが OpenAPI 2.0 (Swagger 2.0) 仕様に準拠していることを示します。"info": API のタイトルや説明など、メタデータを定義します。"host": API のホスト名です。実際には、この値は Named Credential で定義された URL で上書きされます。"paths": API が提供するエンドポイントのリストです。この例では/addという単一のエンドポイントがあります。"post":/addエンドポイントがサポートする HTTP メソッドです。ここでは POST リクエストを受け付けます。"summary"と"description": Flow Builder のアクション選択画面で表示されるラベルや説明文になります。分かりやすい記述を心がけることが重要です。"parameters": この操作が受け取る入力パラメータを定義します。"in": "body"は、リクエストボディでデータを受け取ることを示します。その構造はdefinitionsで定義されたAddRequestオブジェクトを参照しています。"responses": 操作の結果として返されるレスポンスを定義します。"200"は HTTP ステータスコード 200 (成功) の場合のレスポンス構造を示し、AddResponseオブジェクトを参照しています。"definitions": API で使用されるデータモデル (オブジェクト) を定義します。AddRequestはn1とn2という 2つの数値プロパティを持つ入力オブジェクト、AddResponseはresultという数値プロパティを持つ出力オブジェクトです。これらが Flow のアクションの入力変数・出力変数に対応します。
このスキーマを Salesforce に登録すると、Flow Builder で「Calculator Service」カテゴリの中に「add」というアクションが表示されます。このアクションには `n1` と `n2` の入力項目があり、出力として `result` を持つ複合変数 (Apex-defined-variable) を返します。開発者はこのアクションをフローに配置し、変数をマッピングするだけで、外部の電卓サービスを呼び出すことができるようになります。
注意事項
External Services は非常に強力ですが、開発者として留意すべきいくつかの制限事項と考慮点があります。
権限 (Permissions)
External Services を呼び出す Flow を実行するユーザーには、適切な権限が必要です。まず、Flow を実行するための「フローを実行」システム権限が必要です。さらに重要なのは、関連付けられた Named Credential へのアクセス権限です。プロファイルや権限セットを使用して、特定のユーザーグループのみがその Named Credential を経由してコールアウトを実行できるように制御することがベストプラクティスです。
API 制限 (API Limits)
External Services によるコールアウトは、内部的に Apex コールアウトとして処理されるため、Salesforce の標準的なガバナ制限に従います。
- トランザクションあたりのコールアウト数：1つのトランザクション内で実行できるコールアウトは、同期処理で最大100回です。ループ内で External Services のアクションを呼び出す場合は、この制限に抵触しないよう注意が必要です。
- タイムアウト：コールアウトのタイムアウトは最大120秒です。レスポンスが遅い API を呼び出す場合は、タイムアウトエラーが発生する可能性があります。
- ペイロードサイズ：API リクエストおよびレスポンスのペイロードサイズにも制限があります。また、登録する OpenAPI スキーマファイル自体のサイズも 1MB、文字数では 100,000 文字までという制限があります。
エラー処理 (Error Handling)
API 連携において、エラーハンドリングは最も重要な要素の一つです。外部サービスは常に利用可能とは限らず、ネットワークの問題、認証エラー (401/403)、サーバーエラー (5xx) など、様々な理由で失敗する可能性があります。Flow Builder では、アクション要素からフォルトコネクタ (Fault Connector) を引き出すことで、エラー発生時の処理パスを定義できます。フォルトコネクタを使用してエラーをキャッチし、エラー内容をカスタムオブジェクトに記録する、システム管理者にメールで通知する、ユーザーに分かりやすいエラーメッセージを表示するなど、堅牢なエラー処理ロジックを必ず実装してください。
スキーマの互換性 (Schema Compatibility)
External Services は OpenAPI 2.0 と 3.0 の多くの機能をサポートしていますが、すべての仕様を網羅しているわけではありません。例えば、oneOf, anyOf, not といった複雑な複合スキーマや、一部の再帰的な定義はサポートされていない場合があります。スキーマの解析に失敗する場合は、スキーマをよりシンプルな構造にリファクタリングするか、サポートされている形式に準拠しているかを確認する必要があります。Swagger Editor のような外部ツールを使用して、スキーマの妥当性を事前に検証することが推奨されます。
トランザクション管理 (Transaction Control)
Apex と同様に、DML 操作 (レコードの作成・更新・削除) の後にコールアウトを実行することは、未コミットの作業があるため許可されていません。Flow 内でレコードを更新した直後に External Services のアクションを呼び出すとエラーになります。これを回避するには、Flow のトランザクションを分割する必要があります。例えば、間にスクリーン要素を挟む、または `Pause` (待機) 要素を配置することで、前のトランザクションがコミットされ、新しいトランザクションでコールアウトを実行できます。
まとめとベストプラクティス
External Services は、Salesforce プラットフォームにおける API 連携のあり方を大きく変える機能です。開発者にとっては、反復的なコールアウト実装から解放され、より価値の高いビジネスロジックの構築に集中する時間をもたらします。また、管理者やビジネスアナリストにとっても、API 連携のハードルを下げ、アイデアを迅速にプロトタイピングし、実装することを可能にします。
開発者として External Services を最大限に活用するためのベストプラクティスを以下にまとめます。
- 有効なスキーマから始める：API スキーマは External Services の設計図です。Salesforce にアップロードする前に、必ず Swagger Editor や Postman などのツールを使ってスキーマが OpenAPI 仕様に準拠しているか、また意図通りに動作するかを検証してください。
- 常に Named Credential を使用する：エンドポイント URL や認証情報を Flow やコード内にハードコーディングすることは絶対に避けてください。Named Credential を使用することで、セキュリティを確保し、異なる環境 (Sandbox, Production) へのデプロイを容易にします。
- 障害を前提とした設計：API 連携は失敗する可能性があります。常に Flow にフォルトパスを実装し、ログ記録、通知、リトライロジックなど、ビジネス要件に応じた適切なエラーハンドリングを行ってください。
- ガバナ制限を意識する：特に、レコードトリガーフローやループ内で External Services を使用する場合は、コールアウトの回数制限に注意が必要です。処理をバルク化するなど、制限を回避するための設計を検討してください。
- API ファサードを検討する：連携先の API が非常に複雑であったり、External Services がサポートしていないスキーマ構造を持っている場合は、中間にシンプルな API を仲介させる「ファサードパターン」を検討する価値があります。例えば、MuleSoft や Heroku 上で、複雑な API をラップし、Salesforce にとって扱いやすいシンプルな OpenAPI スキーマを公開する軽量なプロキシサービスを構築する方法です。
- バージョン管理：外部 API の仕様は変更されることがあります。スキーマのバージョン管理戦略を立て、API の変更に合わせて External Services の定義と関連する Flow を更新するプロセスを確立しておくことが重要です。
External Services を使いこなすことで、Salesforce 開発者は、より迅速かつ安全に、そして宣言的な方法で、外部世界との強力な連携を実現できます。これは、現代のコネクテッドなビジネス環境において、非常に価値のあるスキルセットと言えるでしょう。
コメント
コメントを投稿