b2c-webservices

Web Services スキル

このスキルでは、Service Framework を使用して B2C Commerce に Web サービス連携を実装する方法を説明します。

概要

Service Framework を使用すると、次の機能を備えた構造化された方法で外部サービスを呼び出せます。

機能	説明
設定	Business Manager で管理するサービス設定
レート制限	外部システムを保護する自動スロットリング
サーキットブレーカー	連鎖的な障害を防ぐ自動障害処理
ログ記録	機密データのフィルタリングを備えた通信ログ
モック	外部呼び出しを行わずにサービスをテスト

サービスの種類

種類	ユースケース	プロトコル
HTTP	REST API、Webhook	HTTP/HTTPS
HTTPForm	フォーム送信	フォームエンコーディングを使用する HTTP/HTTPS
FTP	ファイル転送（非推奨）	FTP
SFTP	セキュアなファイル転送	SFTP
SOAP	SOAP Web サービス	SOAP を使用する HTTP/HTTPS
GENERIC	カスタムプロトコル	任意

Service Framework のコンポーネント

Business Manager の設定

サービスは Administration > Operations > Services で設定します。

1. Service Configuration - 一般設定（有効化、ログ記録、コールバック）
2. Service Profile - レート制限とサーキットブレーカーの設定
3. Service Credential - URL と認証情報

スクリプトコンポーネント

コンポーネント	目的
LocalServiceRegistry	サービスインスタンスを作成
ServiceCallback	リクエスト／レスポンス処理を定義
Service	共通メソッドを備えたベースサービス
Result	ステータスとデータを含むレスポンスオブジェクト

基本パターン

'use strict';

var LocalServiceRegistry = require('dw/svc/LocalServiceRegistry');

var myService = LocalServiceRegistry.createService('my.service.id', {
    /**
     * Configure the request before it is sent
     * @param {dw.svc.HTTPService} svc - The service instance
     * @param {Object} params - Parameters passed to service.call()
     * @returns {string} Request body
     */
    createRequest: function (svc, params) {
        svc.setRequestMethod('POST');
        svc.addHeader('Content-Type', 'application/json');
        return JSON.stringify(params);
    },

    /**
     * Parse the response after a successful call
     * @param {dw.svc.HTTPService} svc - The service instance
     * @param {dw.net.HTTPClient} client - The HTTP client with response
     * @returns {Object} Parsed response
     */
    parseResponse: function (svc, client) {
        return JSON.parse(client.text);
    },

    /**
     * Filter sensitive data from logs (required for production)
     * @param {string} msg - The message to filter
     * @returns {string} Filtered message
     */
    filterLogMessage: function (msg) {
        return msg.replace(/("api_key"\s*:\s*")[^"]+"/g, '$1***"');
    }
});

// Call the service
var result = myService.call({ key: 'value' });

if (result.ok) {
    var data = result.object;
} else {
    var error = result.errorMessage;
}

サービスコールバック

コールバック	必須	説明
createRequest	はい*	リクエストを設定し、本文を返します
parseResponse	はい*	レスポンスを解析し、結果オブジェクトを返します
execute	いいえ	カスタム実行ロジック（デフォルトの処理を置き換えます）
initServiceClient	いいえ	基盤となるクライアントを作成／設定します
mockCall	いいえ	モックレスポンスを返します（実行フェーズのみ）
mockFull	いいえ	モックレスポンスを返します（呼び出し全体）
filterLogMessage	推奨	ログから機密データをフィルタリングします
getRequestLogMessage	いいえ	カスタムリクエストログメッセージ
getResponseLogMessage	いいえ	カスタムレスポンスログメッセージ

*execute を実装する場合を除き必須です

Result オブジェクト

call() メソッドは dw.svc.Result を返します。

プロパティ	型	説明
ok	Boolean	成功した場合は True
status	String	「OK」、「ERROR」、または「SERVICE_UNAVAILABLE」
object	Object	parseResponse からのレスポンス
error	Number	エラーコード（HTTP ステータスなど）
errorMessage	String	エラーの説明
unavailableReason	String	サービスが利用できない理由
mockResult	Boolean	モックコールバックからの結果の場合は True

利用不可の理由

理由	説明
TIMEOUT	呼び出しがタイムアウトしました
RATE_LIMITED	レート制限を超過しました
CIRCUIT_BROKEN	サーキットブレーカーが開いています
DISABLED	サービスが無効です
CONFIG_PROBLEM	設定エラー

エラー処理

var result = myService.call(params);

if (result.ok) {
    return result.object;
}

// Handle different error types
switch (result.status) {
    case 'SERVICE_UNAVAILABLE':
        switch (result.unavailableReason) {
            case 'RATE_LIMITED':
                // Retry later
                break;
            case 'CIRCUIT_BROKEN':
                // Service is down, use fallback
                break;
            case 'TIMEOUT':
                // Request timed out
                break;
        }
        break;
    case 'ERROR':
        // Check HTTP status code
        if (result.error === 401) {
            // Authentication error
        } else if (result.error === 404) {
            // Resource not found
        }
        break;
}

throw new Error('Service error: ' + result.errorMessage);

ログのフィルタリング

本番環境では、機密データの露出を防ぐためにログのフィルタリングが必要です。

var myService = LocalServiceRegistry.createService('my.service', {
    createRequest: function (svc, params) {
        // ... configure request
    },

    parseResponse: function (svc, client) {
        return JSON.parse(client.text);
    },

    /**
     * Filter sensitive data from all log messages
     */
    filterLogMessage: function (msg) {
        // Filter API keys
        msg = msg.replace(/api_key=[^&]+/g, 'api_key=***');
        // Filter authorization headers
        msg = msg.replace(/Authorization:\s*[^\r\n]+/gi, 'Authorization: ***');
        // Filter passwords in JSON
        msg = msg.replace(/("password"\s*:\s*")[^"]+"/g, '$1***"');
        return msg;
    },

    /**
     * Custom request log message (optional)
     */
    getRequestLogMessage: function (request) {
        // Return custom message or null for default
        return 'Request: ' + request.substring(0, 100) + '...';
    },

    /**
     * Custom response log message (optional)
     */
    getResponseLogMessage: function (response) {
        // Return custom message or null for default
        return 'Response received';
    }
});

サービスのモック

外部呼び出しを行わずにテストするには、モックコールバックを使用します。

var myService = LocalServiceRegistry.createService('my.service', {
    createRequest: function (svc, params) {
        svc.setRequestMethod('GET');
        svc.addParam('id', params.id);
        return null;
    },

    parseResponse: function (svc, client) {
        return JSON.parse(client.text);
    },

    /**
     * Mock the execute phase only (createRequest and parseResponse still run)
     */
    mockCall: function (svc, request) {
        return {
            statusCode: 200,
            text: JSON.stringify({ id: 1, name: 'Mock Data' })
        };
    },

    /**
     * Or mock the entire call (replaces all phases)
     */
    mockFull: function (svc, params) {
        return { id: params.id, name: 'Full Mock Data' };
    }
});

// Force mock mode
myService.setMock();
var result = myService.call({ id: 123 });

Business Manager でのサービス設定

サービスの作成

1. Administration > Operations > Services に移動します
2. Service Configurations の下にある New をクリックします
3. 次の項目を入力します。
   • Service ID：一意の識別子（例：my.api.service）
   • Service Type：HTTP、FTP、SOAP など
   • Enabled：有効にする場合はチェックします
   • Profile：プロファイルを選択または作成します
   • Credential：認証情報を選択または作成します
   • Communication Log：デバッグ用に有効にします

サービスプロファイル設定

設定	説明
タイムアウト	最大待機時間（ミリ秒）
レート制限	時間単位あたりの最大呼び出し回数
サーキットブレーカーを有効化	障害処理を自動的に有効化します
サーキットブレーカーの最大呼び出し回数	サーキットブレーカーが開くまでの呼び出し回数
サーキットブレーカーの間隔	障害を追跡する時間枠

サービス認証情報設定

設定	説明
ID	認証情報の識別子
URL	サービスのベース URL
ユーザー	認証に使用するユーザー名
パスワード	認証に使用するパスワード

詳細リファレンス

• HTTP サービス - REST API の統合
• FTP/SFTP サービス - ファイル転送操作
• SOAP サービス - SOAP Web サービスの統合
• サービス XML - サービス設定のインポート／エクスポート

スクリプト API クラス

クラス	説明
dw.svc.LocalServiceRegistry	サービスインスタンスの作成
dw.svc.Service	サービスの基底クラス
dw.svc.HTTPService	HTTP サービスのメソッド
dw.svc.FTPService	FTP/SFTP サービスのメソッド
dw.svc.SOAPService	SOAP サービスのメソッド
dw.svc.Result	サービス呼び出しの結果
dw.svc.ServiceConfig	サービス設定
dw.svc.ServiceProfile	レート制限／サーキットブレーカーの設定
dw.svc.ServiceCredential	認証情報
dw.net.HTTPClient	基盤となる HTTP クライアント
dw.net.FTPClient	基盤となる FTP クライアント
dw.net.SFTPClient	基盤となる SFTP クライアント