Salesforce 外部サービス：コンサルタントのための宣言的API連携ガイド

日付:

背景と適用シナリオ

現代のビジネス環境において、企業は顧客関係管理 (CRM)、基幹業務システム (ERP)、マーケティングオートメーション、物流システムなど、多種多様なSaaSやオンプレミスシステムを併用しています。これらのシステムがサイロ化してしまうと、データが分断され、業務効率が低下し、一貫性のある顧客体験を提供することが困難になります。この課題を解決するのがシステム連携（Integration）です。

従来、Salesforceと外部システムを連携させるには、Apex（Salesforce独自のプログラミング言語）を用いてカスタムコードを記述するのが一般的でした。このアプローチは非常に柔軟性が高い一方で、開発には専門的なスキルが必要であり、開発期間やコスト、そして将来的なメンテナンスの負担が大きくなるという課題がありました。特に、ビジネス要件が頻繁に変化するプロジェクトでは、コードの修正に時間と手間がかかり、ビジネスのスピードに追いつけないケースも少なくありませんでした。

こうした課題に対応するため、SalesforceはExternal Services（外部サービス）という画期的な機能を提供しています。これは、プログラミングを一切行うことなく、外部のREST APIをSalesforceのFlow（フロー）などの宣言的ツール（declarative tools）から直接呼び出すことを可能にする機能です。私たちSalesforceコンサルタントにとって、これはお客様の連携要件を迅速かつ低コストで実現するための強力な武器となります。

具体的な適用シナリオ

  • 住所情報の補完・正規化: 取引先やリードの住所を入力した際に、外部の住所クレンジングAPIを呼び出し、郵便番号の自動入力や、住所表記のゆれを統一する。
  • リアルタイム与信確認: 商談が特定のフェーズに進んだタイミングで、外部の与信情報サービスAPIを呼び出し、取引先の与信を自動で確認し、結果をSalesforceのレコードに記録する。
  • 外部ERPへの注文登録: 商談が成立（Closed Won）した際に、Flowをトリガーして外部のERPシステムに注文情報を自動で作成する。
  • 配送状況の追跡: ケース（問い合わせ）レコードに記録された荷物の追跡番号を基に、配送業者のAPIを呼び出し、最新の配送状況を取得して画面に表示する。
  • 他システムのマスタデータ参照: Salesforce上にマスタデータを二重に持つのではなく、画面フローから外部システムの商品マスタAPIを呼び出し、常に最新の商品情報を参照・選択させる。

これらのシナリオは、ほんの一例です。External Servicesを活用することで、これまでであれば開発プロジェクトとして数週間から数ヶ月かかっていた連携を、数日でプロトタイプを完成させることも可能になります。

原理説明

External Servicesの仕組みは、業界標準のAPI記述フォーマットであるOpenAPI Specification（OpenAPI 仕様）を基盤としています。OpenAPIは、REST APIの構造（エンドポイント、リクエスト、レスポンス、データモデルなど）を機械可読な形式で定義するための仕様です。External Servicesはこの仕様書を読み込み、Salesforceプラットフォーム上でネイティブに動作するアクションへと自動変換します。

連携を実現するまでのプロセスは、大きく以下のステップに分かれています。

  1. OpenAPI仕様書の準備:
    連携したい外部サービスのAPI提供元から、OpenAPI 2.0 (Swagger) または OpenAPI 3.0形式の仕様書（通常はJSONまたはYAMLファイル）を入手します。この仕様書が、APIの「設計図」の役割を果たします。

  2. 認証情報の設定:
    APIの呼び出しには、多くの場合、認証が必要です。Salesforceでは、Named Credential（指定ログイン情報）という機能を使って、APIのエンドポイントURLや認証情報を安全に一元管理します。ここに認証方式（基本認証、OAuth 2.0など）やクレデンシャルを登録しておくことで、仕様書やFlowの中に直接パスワードなどをハードコーディングする必要がなくなり、セキュリティとメンテナンス性が向上します。

  3. 外部サービスの登録:
    Salesforceの[設定]メニューから「外部サービス」を開き、準備したOpenAPI仕様書と作成したNamed Credentialを関連付けて登録します。Salesforceはこの時点で仕様書を解析し、仕様書内で定義されている各API操作（例：「ユーザー取得」「注文作成」）を、Flowから呼び出し可能なInvocable Action（呼び出し可能なアクション）として自動的に生成します。

  4. Flowからの呼び出し:
    Flow Builderを開くと、[アクション]要素の選択肢の中に、登録した外部サービスのアクションが表示されます。これを選択し、APIが必要とする入力パラメータ（例：取引先ID）をマッピングし、APIからの戻り値（例：与信結果）をFlow内の変数に格納して、後続の処理（レコード更新、画面表示など）に活用します。

このように、External ServicesはAPI連携の複雑な部分（HTTPリクエストの構築、JSONのシリアライズ・デシリアライズなど）を完全に抽象化し、コンサルタントや管理者がビジネスロジックの実装に集中できる環境を提供してくれます。

実装例

ここでは、銀行口座の残高を取得するというシンプルなシナリオを例に、External Servicesで利用するOpenAPI仕様書の具体例を見ていきましょう。この例は、Salesforceの公式ドキュメントでよく使用されるサンプルです。

以下のOpenAPI 2.0 (Swagger)仕様書は、特定の口座種別（accountType）のリストを取得するAPIを定義しています。

OpenAPI 2.0 仕様書のサンプル

{
  "swagger": "2.0",
  "info": {
    "title": "Bank Service",
    "description": "API for a simple bank service.",
    "version": "1.0.0"
  },
  "host": "my-bank-service.herokuapp.com",
  "schemes": [
    "https"
  ],
  "paths": {
    "/accounts": {
      "get": {
        "summary": "Get Accounts",
        "description": "Provides a list of bank accounts of a given type.",
        "parameters": [
          {
            "name": "accountType",
            "in": "query",
            "description": "Type of account to fetch",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of accounts.",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Account"
              }
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Account": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "balance": {
          "type": "number"
        }
      }
    }
  }
}

仕様書の解説

  • host: APIのベースURLです。External Servicesでは、この値はNamed Credentialで上書きされるため、実質的には無視されます。
  • paths: APIのエンドポイントを定義します。ここでは/accountsというパスが定義されています。
  • paths./accounts.get: /accountsに対するHTTP GETリクエストの操作を定義しています。summaryは、Flowで表示されるアクションのラベルになります（この場合、「Get Accounts」）。
  • parameters: APIが受け取る入力パラメータを定義します。name: "accountType"、in: "query"とあるので、これは/accounts?accountType=SAVINGSのようにクエリパラメータとして渡されることを意味します。これがFlowアクションの入力項目になります。
  • responses: APIからのレスポンスを定義します。HTTPステータスコード200（成功）の場合、Accountオブジェクトの配列（array）が返されることがわかります。
  • definitions.Account: APIが返すデータの構造（スキーマ）を定義しています。Accountオブジェクトはname、id、balanceという3つのプロパティを持つことが定義されています。これらがFlowアクションの出力変数として利用可能になります。

このJSONファイルをSalesforceに登録すると、Flow Builderのアクション要素に「Bank Service: Get Accounts」というアクションが自動的に生成されます。このアクションには「accountType」という入力項目と、「200」（成功時のレスポンスボディ）という出力項目が含まれ、出力項目は「Accountのリスト」としてアクセスできるようになります。

注意事項

External Servicesは非常に強力ですが、プロジェクトを成功させるためには、その制約や注意点を正しく理解しておくことが不可欠です。お客様への提案や設計の際には、以下の点を必ず考慮してください。

1. OpenAPI仕様書のサポート範囲

External ServicesはOpenAPI 2.0および3.0をサポートしますが、仕様の全てに対応しているわけではありません。特に、以下のような複雑なスキーマはサポートされていないか、限定的なサポートとなります。

  • 複合スキーマ (oneOf, anyOf, not): 複数のスキーマのうちのいずれか、というような条件分岐的な定義はサポートされません。
  • 再帰的なスキーマ定義: 自分自身を参照するようなデータ構造は、特定の階層までしかサポートされません。
  • ワイルドカード (additionalProperties: true): 未定義のプロパティを許容するスキーマは、予期せぬ動作を引き起こす可能性があります。

対策: API提供元と協力し、External Servicesが解釈可能な、よりシンプルで具体的なスキーマを提供してもらうか、中間API（MuleSoftなど）を介してスキーマを変換する必要があります。

2. ガバナ制限 (Governor Limits)

External ServicesによるAPI呼び出しは、SalesforceプラットフォームのCallout（コールアウト）制限に従います。1つのトランザクション内で実行できるコールアウトの数（例：100回）や、合計実行時間（例：120秒）には上限があります。大量のレコードをループ処理で更新しながら、ループの都度APIを呼び出すような設計は、容易にこの制限に抵触します。

対策: 設計段階で、1トランザクションあたりのコールアウト数を慎重に見積もります。必要であれば、Flowを一括処理に対応した設計にするか、プラットフォームイベントなどを利用して非同期処理に分割することを検討します。

3. エラーハンドリング

外部APIはいつでも成功するとは限りません。ネットワークの問題、サーバーダウン、不正なリクエストなど、様々な理由でエラーが返される可能性があります。Flow内でAPIを呼び出す際は、必ずFault Path（フォルトパス）を構成し、エラー発生時の処理を定義する必要があります。

対策: Fault Pathでエラーをキャッチし、エラー内容をカスタムオブジェクトに記録したり、システム管理者にメールで通知したり、画面フローであればユーザーに分かりやすいエラーメッセージを表示したりする処理を実装します。API呼び出しが失敗した場合の代替フローを常に考慮することが重要です。これにより、システムの堅牢性が大幅に向上します。

4. トランザクション制御

Flowのトランザクションにおいて、コールアウトは特別な意味を持ちます。コールアウトを実行する前に行ったDML操作（レコードの作成・更新・削除）は、コールアウトの時点でコミットされ、後続の処理でエラーが発生してもロールバックされません。例えば、「取引先を作成」→「外部APIを呼び出し」→「商談を作成（ここでエラー）」というFlowの場合、取引先は作成されたまま残ってしまいます。

対策: 可能な限り、コールアウトはトランザクションの最初の方で行うか、コールアウト後の処理で失敗する可能性が低いように設計します。データの整合性が非常に重要な要件の場合は、Apexによるより高度なトランザクション制御が必要になる可能性も検討します。

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

External Servicesは、Salesforceと外部システムとの連携を民主化し、開発者だけでなく管理者やコンサルタントもが迅速にインテグレーションを構築できる強力なツールです。ビジネス要件をコードを書かずに素早く形にできるため、PoC（概念実証）やプロトタイピングにも最適です。

コンサルタントとしてExternal Servicesを最大限に活用し、プロジェクトを成功に導くためのベストプラクティスを以下にまとめます。

  1. 堅牢なOpenAPI仕様書から始める:
    連携プロジェクトの成否は、OpenAPI仕様書の品質に大きく依存します。事前に仕様書をオンラインのバリデーターで検証し、External Servicesのサポート範囲内であることを確認しましょう。API提供者との密なコミュニケーションが鍵となります。

  2. Named Credentialを徹底活用する:
    認証情報やエンドポイントURLをハードコーディングすることは絶対に避けてください。Named Credentialを使用することで、セキュリティを確保し、環境間（Sandboxから本番）の移行をスムーズにします。

  3. 失敗を前提とした設計を心がける:
    「外部APIは必ず失敗する可能性がある」という前提に立ち、Flow内でのエラーハンドリングを徹底しましょう。ユーザー体験とデータの整合性を守るために、Fault Pathの設計は必須です。

  4. 適切なツールを使い分ける:
    External Servicesは万能ではありません。非常に複雑なデータ変換ロジックが必要な場合、サポート外の認証方式が求められる場合、または厳密なトランザクション制御が必要な場合は、依然としてApexコールアウトやMuleSoftのような連携プラットフォームが最適な選択肢となります。それぞれのツールの長所と短所を理解し、要件に最も適したソリューションを提案することがコンサルタントの役割です。

  5. 徹底的なテスト:
    Sandbox環境で、正常系だけでなく、APIがエラーを返す異常系のテストも必ず実施してください。予期せぬレスポンスやタイムアウトなど、様々なシナリオを想定してテストすることで、本番環境でのトラブルを未然に防ぐことができます。

External Servicesを正しく理解し活用することで、私たちはクライアントのビジネス課題を、これまで以上に迅速かつ効果的に解決することができます。宣言的なアプローチで、変化し続けるビジネスニーズに柔軟に対応していきましょう。

コメント

コメントを投稿