Salesforce外部連携の最適化：名前付き資格情報（Named Credentials）を徹底解説

日付:

背景と応用シーン

Salesforceは、顧客関係管理（CRM）の中核として、多くの企業にとって不可欠なプラットフォームです。しかし、その真価は、外部システムとのシームレスな連携によって最大限に発揮されます。例えば、ERPシステムからの注文情報の取得、外部の顧客データプラットフォームへの更新、マイクロサービスへのリアルタイムなAPIコールなど、Salesforceが外部と通信するシナリオは数多く存在します。これまで、これらの外部連携を行う際には、エンドポイントURL（Endpoint URL）や認証情報（Authentication Details）をApexコード内に直接記述したり、カスタム設定（Custom Settings）やカスタムメタデータ（Custom Metadata）に保存したりする方法が一般的でした。

しかし、これらの方法にはいくつかの課題がありました。第一に、セキュリティ上のリスクです。特に認証情報（APIキー、ユーザー名、パスワードなど）をコードや設定に直接保存することは、情報漏洩のリスクを高めます。第二に、管理の複雑さです。エンドポイントURLや認証情報が変更されるたびに、コードを修正・再デプロイする必要があり、これが運用コストの増大やエラーの発生につながる可能性がありました。第三に、認証プロトコルの多様性への対応です。OAuth 2.0、JWT、基本認証（Basic Authentication）など、外部システムが要求する認証方式は多岐にわたり、それぞれに対応するコードを記述するのは開発者の負担でした。

これらの課題を解決するためにSalesforceが提供しているのが、名前付き資格情報（Named Credentials）です。名前付き資格情報（Named Credentials）は、外部システムのエンドポイントURLと認証情報を一元的に管理する設定機能です。これにより、Apexコードから外部システムを呼び出す際に、具体的なURLや認証情報を直接記述することなく、定義された名前（Name）を参照するだけで安全かつ簡単にAPIコールを実行できるようになります。

名前付き資格情報（Named Credentials）の主な応用シーンは以下の通りです。

  • ERPシステムとの連携：注文状況の確認、在庫情報の同期。
  • 外部データサービス：信用情報、地図情報、郵便番号検索などのAPIの利用。
  • マーケティングオートメーションプラットフォーム：リード情報やキャンペーンデータの同期。
  • カスタムマイクロサービス：企業のビジネスロジックを実装した外部サービスへのAPIコール。
  • 支払いゲートウェイ：安全な支払い処理のための外部システム連携。

これらのシナリオにおいて、名前付き資格情報（Named Credentials）は、セキュリティの強化、開発の簡素化、そして運用効率の向上という点で、極めて重要な役割を果たします。

原理説明

名前付き資格情報（Named Credentials）の核心は、外部システムへのコールアウト（Callout）に必要なエンドポイントURLと認証プロセスをSalesforceプラットフォームが肩代わりするという点にあります。開発者はApexコード内で、具体的なURLの代わりにcallout:MyNamedCredentialという形式で名前付き資格情報（Named Credentials）を参照します。これにより、Salesforceプラットフォームが自動的にその名前付き資格情報に紐づけられた実際のURLと認証情報を使用して、外部システムへの接続を確立します。

名前付き資格情報（Named Credentials）の主要な構成要素は以下の通りです。

  • URL：外部システムのエンドポイントURL。例えば、https://api.example.com/v1/。
  • 認証プロトコル（Authentication Protocol）：外部システムへの認証方式。Salesforceは、OAuth 2.0（OAuth 2.0）、JWT（JSON Web Token）、基本認証（Basic Authentication）、AWS署名バージョン4（AWS Signature Version 4）など、多様なプロトコルをサポートしています。
  • 外部資格情報（External Credentials）：これは、名前付き資格情報（Named Credentials）がユーザーごとの認証やより複雑な認証フローをサポートするために使用する新しい機能です。外部資格情報（External Credentials）は、認証設定（例：OAuth 2.0クライアントID、シークレット、認証URLなど）を定義し、それを特定のプリンシパル（Principal）に紐づけます。プリンシパルは、外部システムのユーザーアカウントを表し、ユーザーごとの認証や組織全体の認証を制御します。一つの名前付き資格情報（Named Credentials）は、複数の外部資格情報（External Credentials）を参照でき、さらに各外部資格情報（External Credentials）は複数のプリンシパルを持つことができます。これにより、より柔軟でセキュアな認証管理が可能になります。
  • 権限セット（Permission Sets）：外部資格情報（External Credentials）とプリンシパルは、権限セット（Permission Sets）を通じてユーザーに割り当てられます。これにより、どのユーザーがどの認証情報を使用して外部システムにアクセスできるかを細かく制御できます。例えば、特定のユーザーグループのみが、特定の外部システムのAPIにアクセスできるよう設定できます。

名前付き資格情報（Named Credentials）の設定プロセスは、主に以下のステップで構成されます。

  1. Salesforceの「設定（Setup）」から「名前付き資格情報（Named Credentials）」を検索し、新規作成します。
  2. 「名前（Name）」と「URL」を指定します。この「名前（Name）」がApexコードから参照する際に使用されます。
  3. 認証タイプを選択し、必要に応じて「外部資格情報（External Credentials）」を関連付けます。
  4. 外部資格情報（External Credentials）を使用する場合は、そちらも新規作成し、認証プロトコルと認証設定を定義します。
  5. 外部資格情報（External Credentials）にプリンシパルを追加し、そのプリンシパルへのアクセスを許可する権限セット（Permission Sets）を設定します。

このメカニズムにより、Apexコードは認証の詳細を意識することなく、シンプルかつセキュアに外部連携を実行できます。認証情報がSalesforceの管理下に置かれることで、コードの可読性、保守性、そしてセキュリティが大幅に向上します。さらに、Sandbox環境（Sandbox Environment）と本番環境（Production Environment）で異なるエンドポイントURLや認証情報を使用する場合でも、名前付き資格情報（Named Credentials）の設定を変更するだけで済み、コードの変更は不要となります。

例コード

ここでは、名前付き資格情報（Named Credentials）を使用して外部APIを呼び出すApexコードの例を示します。この例では、MyExternalSystemという名前の名前付き資格情報（Named Credentials）が事前に設定されており、そのURLがhttps://api.example.com/dataに設定されていると仮定します。

/**
 * @description MyExternalSystemという名前付き資格情報を使用して外部APIを呼び出すユーティリティクラス。
 */
public with sharing class ExternalApiCalloutService {

    /**
     * @description 名前付き資格情報を使用して、指定されたパスにGETリクエストを送信します。
     * @param path 外部システムのAPIパス (例: /users, /products/123)
     * @return 外部APIからのレスポンスボディ (JSON形式)
     * @throws CalloutException API呼び出し中にエラーが発生した場合
     */
    public static String fetchDataFromExternalSystem(String path) {
        // 新しいHTTPリクエストオブジェクトを作成
        HttpRequest request = new HttpRequest();
        
        // エンドポイントを設定。ここでは 'callout:MyExternalSystem' が名前付き資格情報を参照します。
        // パスは 'MyExternalSystem' のURLの後に追加されます。
        // 例: MyExternalSystemのURLが 'https://api.example.com' の場合、
        // エンドポイントは 'https://api.example.com/v1/users' となります。
        request.setEndpoint('callout:MyExternalSystem' + path);
        
        // HTTPメソッドをGETに設定
        request.setMethod('GET');
        
        // 必要に応じてヘッダーを追加 (例: Acceptヘッダー)
        request.setHeader('Accept', 'application/json');
        
        // タイムアウト設定 (ミリ秒単位, デフォルトは120000ms = 120秒)
        // ここでは60秒に設定
        request.setTimeout(60000); 

        // HTTPオブジェクトを作成してリクエストを送信
        Http http = new Http();
        HttpResponse response = null;

        try {
            // 外部APIを呼び出し
            response = http.send(request);

            // レスポンスのステータスコードを確認
            if (response.getStatusCode() == 200) {
                // 成功した場合、レスポンスボディを返す
                return response.getBody();
            } else {
                // エラーレスポンスの場合、詳細なエラーメッセージをスロー
                throw new CalloutException(
                    'APIコールアウトエラー: ' + response.getStatusCode() + ' ' + response.getStatus() + 
                    '. レスポンスボディ: ' + response.getBody()
                );
            }
        } catch (System.CalloutException e) {
            // コールアウト中にネットワークエラーやタイムアウトが発生した場合
            throw new CalloutException('コールアウト中にシステムエラーが発生しました: ' + e.getMessage());
        } catch (Exception e) {
            // その他の予期せぬエラー
            throw new CalloutException('予期せぬエラーが発生しました: ' + e.getMessage());
        }
    }

    /**
     * @description 名前付き資格情報を使用して、指定されたパスにPOSTリクエストを送信します。
     * @param path 外部システムのAPIパス
     * @param requestBody POSTリクエストのボディ (JSON文字列)
     * @return 外部APIからのレスポンスボディ (JSON形式)
     * @throws CalloutException API呼び出し中にエラーが発生した場合
     */
    public static String postDataToExternalSystem(String path, String requestBody) {
        HttpRequest request = new HttpRequest();
        request.setEndpoint('callout:MyExternalSystem' + path);
        request.setMethod('POST');
        request.setHeader('Content-Type', 'application/json');
        request.setHeader('Accept', 'application/json');
        request.setBody(requestBody); // リクエストボディを設定
        request.setTimeout(60000); 

        Http http = new Http();
        HttpResponse response = null;

        try {
            response = http.send(request);

            if (response.getStatusCode() >= 200 && response.getStatusCode() < 300) {
                return response.getBody();
            } else {
                throw new CalloutException(
                    'APIコールアウトエラー: ' + response.getStatusCode() + ' ' + response.getStatus() + 
                    '. レスポンスボディ: ' + response.getBody()
                );
            }
        } catch (System.CalloutException e) {
            throw new CalloutException('コールアウト中にシステムエラーが発生しました: ' + e.getMessage());
        } catch (Exception e) {
            throw new CalloutException('予期せぬエラーが発生しました: ' + e.getMessage());
        }
    }

    // 別のメソッドから上記のサービスを呼び出す例
    public static void exampleUsage() {
        try {
            // GETリクエストの例
            String userData = fetchDataFromExternalSystem('/v1/users/123');
            System.debug('取得したユーザーデータ: ' + userData);

            // POSTリクエストの例
            String newProductJson = '{"name": "New Product", "price": 99.99}';
            String postResponse = postDataToExternalSystem('/v1/products', newProductJson);
            System.debug('POSTリクエストのレスポンス: ' + postResponse);

        } catch (CalloutException e) {
            System.debug(LoggingLevel.ERROR, '外部API呼び出しエラー: ' + e.getMessage());
            // 必要に応じてエラー処理ロジックを追加 (例: エラーログ、ユーザーへの通知)
        }
    }
}

上記のコードは、Salesforceの公式ドキュメントで説明されているHttpRequestおよびHttpResponseオブジェクトの使用方法と、名前付き資格情報（Named Credentials）をエンドポイントURLに含めるcallout:プレフィックスの適用方法に厳密に基づいています。

注意事項

名前付き資格情報（Named Credentials）を効果的かつ安全に利用するためには、いくつかの重要な考慮事項があります。

権限（Permissions）

名前付き資格情報（Named Credentials）およびそれに紐づく外部資格情報（External Credentials）のセキュリティモデルを理解することは非常に重要です。特に、外部資格情報（External Credentials）を使用する場合、特定のユーザーが外部システムへのコールアウトを実行できるようにするためには、適切な権限セット（Permission Sets）を割り当てる必要があります。

  • 外部資格情報へのアクセス権限：外部資格情報（External Credentials）がプリンシパル（Principal）を持つ場合、そのプリンシパルを介して認証を行うためには、ユーザーは対応する権限セット（Permission Sets）を持っている必要があります。この権限セットは、外部資格情報（External Credentials）の設定時に「プリンシパルへのアクセス（Access to Principal）」として指定されます。
  • 名前付き資格情報への参照：Apexクラス自体は、名前付き資格情報（Named Credentials）を直接参照するために特別な権限を必要としません。しかし、そのApexクラスが実行されるコンテキストのユーザーが、関連する外部資格情報（External Credentials）へのアクセス権限を持っている必要があります。
  • 管理者権限：名前付き資格情報（Named Credentials）および外部資格情報（External Credentials）の作成、編集、削除には、「Customize Application」または「Manage Named Credentials」の権限が必要です。

API制限（API Limits）

Apexのコールアウトには、Salesforceの標準的なガバナ制限（Governor Limits）が適用されます。これらの制限を意識せずに大量のAPIコールを行うと、トランザクションが失敗する可能性があります。

  • 1トランザクションあたりのコールアウト数：同期Apexでは最大100回、非同期Apex（FutureメソッドやQueueable Apexなど）ではより高い制限が設定される場合があります。
  • コールアウトの合計タイムアウト：1回のコールアウトの最大タイムアウトは120秒です。全てのコールアウトの合計タイムアウトも制限されます。
  • 応答サイズ：コールアウトによって返される応答ボディのサイズにも制限があります。

これらの制限を超えることが予想される場合は、コールアウトをバッチ処理したり、非同期処理（Futureメソッド、Queueable Apex、Batch Apex）を利用して処理を分散させるなどの設計が必要です。

エラー処理（Error Handling）

外部システムとの連携では、ネットワークの問題、外部APIのダウンタイム、認証エラー、無効なリクエストなど、さまざまなエラーが発生する可能性があります。堅牢なエラー処理を実装することが不可欠です。

  • try-catchブロック：HttpRequest.send()メソッドはSystem.CalloutExceptionをスローする可能性があるため、必ずtry-catchブロックで囲む必要があります。これにより、ネットワークエラーやタイムアウトなどの予期せぬ問題に対応できます。
  • HTTPステータスコードの確認：HttpResponseオブジェクトから返されるHTTPステータスコードを常に確認し、2xxの成功レスポンス以外の場合には、エラーとして適切に処理します。4xx（クライアントエラー）や5xx（サーバーエラー）のコードは、外部システム側での問題を示唆しています。
  • 詳細なログ記録：エラーが発生した際には、スタックトレース、リクエストの詳細、レスポンスボディ（可能な場合）などの詳細情報をログに記録し、問題の原因特定に役立てます。System.debug(LoggingLevel.ERROR, ...)を使用するか、カスタムエラーロギングメカニズムを実装します。
  • リトライロジック：一時的なネットワークの問題や外部APIの短時間の停止に対応するため、指数バックオフ（Exponential Backoff）などの戦略を用いたリトライロジックの実装を検討します。ただし、ガバナ制限に注意が必要です。

セキュリティに関する考慮事項

  • TLS/SSL：名前付き資格情報（Named Credentials）を使用する際、Salesforceは常にHTTPSを介して外部システムと通信します。これは通信の暗号化を保証しますが、外部システムの証明書が有効であることを確認する必要があります。
  • 最小権限の原則：外部資格情報（External Credentials）のプリンシパルには、外部システム上で必要最小限の権限のみを付与するようにします。
  • 外部資格情報の管理：外部資格情報（External Credentials）に保存される認証情報は機密性が高いため、アクセスを厳しく制限し、定期的にレビュー・更新することが推奨されます。

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

名前付き資格情報（Named Credentials）は、Salesforceと外部システム間のセキュアで効率的な連携を実現するための強力な機能です。その利用は、コードの簡素化、セキュリティの向上、およびメンテナンスの容易さをもたらします。

まとめ

  • セキュリティの強化：認証情報がSalesforceプラットフォームによって安全に管理され、Apexコードにハードコードする必要がなくなります。これにより、情報漏洩のリスクが大幅に軽減されます。
  • 開発の簡素化：開発者はエンドポイントURLや認証プロトコルの詳細を意識することなく、callout:MyNamedCredentialの形式で簡単に外部システムを呼び出すことができます。
  • 管理の容易さ：外部システムのエンドポイントURLや認証情報が変更された場合でも、Salesforceの設定画面で名前付き資格情報（Named Credentials）を更新するだけで済み、コードの変更や再デプロイは不要です。
  • 柔軟な認証：外部資格情報（External Credentials）との組み合わせにより、組織全体の認証からユーザーごとの認証まで、多様な認証シナリオに対応できます。

ベストプラクティス

  1. 常に名前付き資格情報を使用する：外部システムへのコールアウトは、常に名前付き資格情報（Named Credentials）を介して行うべきです。これは、セキュリティ、保守性、およびプラットフォームの将来的な機能拡張への適応性の観点から最も推奨される方法です。
  2. 明確で意味のある名前を付ける：名前付き資格情報（Named Credentials）には、その目的や接続先のシステムが明確にわかるような名前を付けましょう（例: ERP_System_API, PaymentGateway_Prod）。
  3. 外部資格情報とプリンシパルを最大限に活用する：特にOAuth 2.0やユーザーごとの認証が必要な場合は、外部資格情報（External Credentials）とそのプリンシパルを積極的に使用し、権限セット（Permission Sets）でアクセスを制御します。これにより、よりきめ細やかなセキュリティ管理が可能になります。
  4. 環境ごとの設定を分離する：Sandbox環境（Sandbox Environment）と本番環境（Production Environment）で異なるエンドポイントや認証情報を使用する場合は、それぞれの環境で適切な名前付き資格情報（Named Credentials）が設定されていることを確認します。可能な限り、設定はパイプラインで自動化します。
  5. 堅牢なエラー処理とロギングを実装する：前述の通り、外部連携におけるエラーは避けられないものです。適切なtry-catchブロック、HTTPステータスコードの確認、詳細なエラーロギング、そして場合によってはリトライメカニズムを導入し、システムの信頼性を高めます。
  6. ガバナ制限を考慮した設計：Salesforceのガバナ制限、特にコールアウトの制限を常に念頭に置き、大量のデータを処理する場合は、非同期処理やバッチ処理を検討します。
  7. 定期的なレビューと更新：外部システムのAPI変更、認証情報の有効期限切れ、セキュリティポリシーの変更などに合わせて、名前付き資格情報（Named Credentials）および外部資格情報（External Credentials）の設定を定期的にレビューし、必要に応じて更新します。

これらのベストプラクティスを遵守することで、Salesforceを基盤とした統合ソリューションの堅牢性と効率性を大幅に向上させることができるでしょう。

コメント

コメントを投稿