Salesforce 外部サービスの徹底解説：宣言的アプローチによるAPI連携

日付:

背景と適用シナリオ

Salesforce 統合エンジニアの皆さん、こんにちは。Salesforce を中心としたエンタープライズアーキテクチャにおいて、外部システムとのデータ連携は避けて通れない重要なテーマです。従来、外部の REST API を呼び出すためには、主に Apex コードを記述する必要がありました。Apex Callout は非常に柔軟で強力ですが、いくつかの課題も抱えています。

第一に、専門的な開発スキルが必要であること。第二に、認証情報の管理（例えば、API キーや OAuth トークン）が煩雑になりがちで、セキュリティリスクを伴うこと。そして第三に、開発とテスト、デプロイメントに時間がかかり、ビジネスの俊敏性を損なう可能性があることです。

このような課題を解決するために Salesforce が提供しているのが、External Services（外部サービス）です。External Services は、API の仕様書（OpenAPI 形式）を登録するだけで、その API の各操作を Flow や Einstein Bots から直接呼び出せる「呼び出し可能なアクション（Invocable Action）」として自動的に生成してくれる、画期的な宣言的インテグレーションツールです。これにより、コードを一行も書かずに、クリック操作だけで外部 API との連携を実装できます。

具体的な適用シナリオ：

  • 金融サービス：取引先や商談の作成時に、外部の信用情報機関の API を呼び出して与信スコアを取得し、Salesforce のレコードに自動で記録する。
  • 物流・配送：注文レコードのステータスが「出荷済み」になった際に、配送業者の API を叩いて追跡番号を取得し、顧客に通知する。
  • データエンリッチメント：新しいリードが作成されたら、外部の企業情報データベース API を利用して、従業員数や業種などの情報を補完する。
  • コミュニケーション：重要なケースがエスカレーションされた場合に、Slack や Microsoft Teams の API を呼び出して、担当チャネルに即時通知を送信する。

このように、External Services は、プロセスの自動化を Salesforce プラットフォームの外にまで拡張し、よりインテリジェントで効率的な業務フローを構築するための強力な武器となります。

原理の説明

External Services の仕組みは非常にシンプルかつエレガントです。その中核をなすのは、API の「契約書」とも言える OpenAPI Specification です。

OpenAPI（以前は Swaggerとして知られていました）は、RESTful API の構造を記述するための標準的な仕様です。この仕様書には、利用可能なエンドポイント、各エンドポイントが受け付ける操作（GET, POST, PUT, DELETE など）、パラメータ、リクエストボディの構造、そしてレスポンスの形式などが、機械可読な形式（通常は JSON または YAML）で定義されています。

External Services のワークフローは以下のようになります。

  1. スキーマの登録：インテグレーションエンジニアまたは管理者が、対象 API の OpenAPI 2.0 または 3.0 仕様書を Salesforce にアップロードします。
  2. アクションの生成：Salesforce プラットフォームは仕様書を解析し、定義されている各 API 操作（例：POST /users や GET /accounts/{id}）に対して、一意の Invocable Action を自動で生成します。このアクションは、仕様書で定義された入力パラメータ（例：ユーザー名、メールアドレス）と出力パラメータ（例：作成されたユーザーの ID、アカウント情報）を厳密に反映します。
  3. 認証の構成：API への接続認証は、Named Credentials（指定ログイン情報）を使用して一元管理されます。Named Credentials には、API のエンドポイント URL、認証プロトコル（Basic 認証、OAuth 2.0 など）、および必要な認証情報（ユーザー名、パスワード、コンシューマキーなど）を安全に格納します。External Services の設定時にこの Named Credential を紐付けることで、Flow の定義から実際の認証情報を完全に分離し、セキュリティとメンテナンス性を大幅に向上させます。
  4. Flow での利用：Flow Builder の「アクション」要素を追加する際に、生成されたアクションを検索して選択できます。UI 上で、Flow 内の変数やリソースをアクションの入力パラメータにマッピングし、アクションの実行結果（出力）を後続の処理で利用することが可能です。

このアーキテクチャにより、API 連携のロジックと、認証やエンドポイントといった環境依存の構成情報とを綺麗に分離できます。例えば、接続先 API の URL がサンドボックス環境と本番環境で異なる場合でも、Flow を修正する必要はなく、各環境の Named Credential の設定を変更するだけで対応できます。これは、インテグレーションエンジニアにとって非常に大きなメリットです。

示例代码

ここでは、External Services がどのように機能するかを具体的に示すため、Salesforce の公式ドキュメントで提供されているシンプルな銀行口座サービス API の OpenAPI 2.0 スキーマを例に挙げます。このスキーマは、新しい口座を追加する操作（`addAccount`）を定義しています。

OpenAPI 2.0 スキーマの例

以下は、口座名と残高を指定して新しい銀行口座を作成する API の仕様です。 

{
  "swagger": "2.0",
  "info": {
    "title": "Simple Account and Bank Service",
    "description": "A simple API for creating a bank account.",
    "version": "1.0.0"
  },
  "host": "my-simple-bank.com",
  "schemes": [
    "https"
  ],
  "basePath": "/accounts",
  "paths": {
    "/": {
      "post": {
        "summary": "Add a new account",
        "description": "Creates a new bank account with an initial balance.",
        "operationId": "addAccount",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "description": "Account object that needs to be added to the bank",
            "required": true,
            "schema": {
              "$ref": "#/definitions/Account"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully created",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Account"
              }
            }
          },
          "400": {
            "description": "Invalid input"
          }
        }
      }
    }
  },
  "definitions": {
    "Account": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "balance": {
          "type": "number"
        }
      }
    }
  }
}

スキーマの解説：

  • "host", "basePath": API のベース URL を定義しますが、External Services では Named Credential で指定されたエンドポイントが優先されます。
  • "paths": API のエンドポイント（この場合はルート `/`）と HTTP メソッド（`post`）を定義します。
  • "operationId": "addAccount": この値が、Salesforce 内で生成される Invocable Action の名前の基になります。通常、「外部サービス名.operationId」という形式（例：`BankService.addAccount`）になります。
  • "parameters": API が受け取る入力を定義します。ここでは、リクエストボディとして Account オブジェクトを受け取ることが示されています。
  • "definitions": { "Account": ... }: Account というデータ構造を定義しています。これには name (string) と balance (number) という 2 つのプロパティが含まれます。Salesforce はこの定義を解析し、Flow 内で対応する Apex 定義変数を作成します。

Flow での利用方法

上記のスキーマを「BankService」という名前で External Service として登録すると、Flow Builder で以下のように利用できます。

  1. 画面フローまたは自動起動フローを作成します。
  2. キャンバスに「アクション」要素をドラッグします。
  3. カテゴリで「外部サービス」を選択すると、「BankService」が表示されます。その中に「addAccount」というアクションが見つかります。
  4. 「addAccount」アクションを選択すると、入力パラメータのセクションが表示されます。ここには、「body」という入力項目があります。
  5. 「body」の値を設定するために、Flow 内で新しい変数を作成します。データ型は「Apex 定義」、Apex クラスは自動生成された `ExternalService__BankService_Account` を選択します。
  6. この Apex 定義変数に、例えば「名前(name)」と「残高(balance)」の値を割り当てます。（例：`accountInput.name = 'My New Account'`, `accountInput.balance = 1000`）
  7. 「addAccount」アクションの「body」入力に、この `accountInput` 変数を設定します。
  8. アクションの出力は、`200` のレスポンスとして Flow の変数に格納され、後続の処理（例：作成された口座情報を画面に表示、カスタムオブジェクトに記録など）で利用できます。

このように、スキーマを登録するだけで、複雑なデータ構造も Flow の中で型安全に扱うことが可能になります。

注意事項

External Services は非常に強力ですが、利用にあたってはいくつかの制限と注意点を理解しておく必要があります。

権限

  • External Services の作成・編集には「アプリケーションのカスタマイズ」権限が必要です。
  • Flow を実行するユーザーには「フローを実行」権限が必要です。
  • また、Flow を実行するユーザーは、その External Service に紐づけられた Named Credential へのアクセス権限を持っている必要があります。プロファイルまたは権限セットでアクセスを許可してください。

API 制限

  • ガバナ制限：External Services によるコールアウトも、Apex Callout と同様に Salesforce のガバナ制限（トランザクションあたり 100 回のコールアウトなど）の対象となります。
  • スキーマの制限：登録できる OpenAPI スキーマのサイズには上限があります（例：OpenAPI 2.0 で 100,000 文字）。また、1 つのスキーマで定義できる操作の数や、オブジェクトのプロパティ数にも制限が存在します。常に最新の公式ドキュメントで制限値を確認してください。
  • タイムアウト：コールアウトのタイムアウトは最大 120 秒です。長時間の処理を伴う API との連携には注意が必要です。
  • 非対応のスキーマ構造：全ての OpenAPI 仕様がサポートされているわけではありません。例えば、`oneOf`, `anyOf`, `allOf` といった複合スキーマや、再帰的なスキーマ定義（循環参照）はサポートされていません。登録前にスキーマがサポート範囲内であることを確認する必要があります。

エラー処理

インテグレーションにおいて、エラーハンドリングは最も重要な要素の一つです。External Services を呼び出す Flow の「アクション」要素からは、「フォルトコネクタ」を引くことができます。API コールが失敗した場合（例：4xx や 5xx の HTTP ステータスコードが返された、ネットワークエラーが発生したなど）、フローの実行は通常のパスではなく、このフォルトパスに進みます。

フォルトパスでは、`$Flow.FaultMessage` というグローバル変数にエラーの詳細情報が格納されます。この変数を画面に表示したり、エラーログ用のカスタムオブジェクトに記録したり、管理者にメールで通知したりするなど、適切なエラー処理を必ず実装してください。これを怠ると、問題が発生した際に原因の特定が非常に困難になります。

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

External Services は、Salesforce プラットフォームにおける API インテグレーションのあり方を大きく変える機能です。コード記述の必要性をなくし、開発サイクルを劇的に短縮させ、より多くの人々（特にシステム管理者やビジネスアナリスト）がインテグレーションの構築に参加できるようにします。

統合エンジニアとして External Services を最大限に活用するためのベストプラクティスを以下にまとめます。

  1. Named Credentials の徹底活用：認証情報やエンドポイントのハードコーディングは絶対に避けてください。Named Credentials を使用することで、セキュリティを強化し、環境間の移行を容易にします。
  2. API のモジュール性：可能であれば、連携先の API は細かく分割された、単一の責任を持つ操作（マイクロサービス的なアプローチ）で設計されていることが望ましいです。これにより、Flow の中で再利用しやすく、管理しやすいアクションが生成されます。
  3. 事前のスキーマ検証：Salesforce にアップロードする前に、Swagger Editor などの外部ツールを使用して OpenAPI スキーマが構文的に正しいことを検証してください。これにより、登録時の不要なエラーを防げます。
  4. 堅牢なエラーハンドリング：全ての External Services アクションには、必ずフォルトパスを実装してください。ユーザーへのフィードバックや、問題追跡のためのログ記録は必須です。
  5. バージョニング戦略：連携先の API がバージョンアップされた場合、新しいスキーマで新しい External Service を作成し、既存の Flow を新しいバージョンのアクションを使用するように段階的に更新するアプローチを推奨します。
  6. Apex との使い分け：External Services は万能ではありません。非常に複雑なデータ変換ロジックが必要な場合、サポートされていない認証方式を利用する場合、または SOAP API と連携する必要がある場合は、従来通り Apex Callout を使用するのが適切な選択です。適材適所でツールを使い分けることが、優れたインテグレーションアーキテクチャの鍵となります。

External Services を正しく理解し、これらのベストプラクティスを実践することで、Salesforce をハブとした、より迅速で、安全かつスケーラブルなシステム連携を実現できるでしょう。

コメント

コメントを投稿