SOAPエンドポイントを手渡されたとします。それは、経理チームがまだ頼っているレガシーな通貨換算ツールかもしれませんし、パートナーが.NETで運用している注文管理ウェブサービスかもしれません。あなたはそれを呼び出し、契約通りの結果が返されることを確認し、周囲のコードが変更されてもそれが正しく維持されることを証明する必要があります。RESTツールはSOAPにはあまり適していません。なぜなら、SOAPは完全なXMLエンベロープ、特定のContent-Type、そしてすべての操作を記述するWSDLを必要とするからです。
Apidogは、REST、GraphQL、gRPCと並行してSOAPおよびWebServiceリクエストを処理するため、スタック内の唯一のレガシーサービスのために別のアプリを必要としません。このガイドでは、SOAPリクエストを手動で送信する方法と、Apidogが環境とエンドポイントを構築するためにWSDLをインポートする方法という、2つの文書化されたパスについて説明します。まず、より広範なプロトコルの全体像を知りたい場合は、REST、GraphQL、gRPC、およびSOAPの比較がそれぞれの役割を解説しています。エンベロープ構造の正式な定義については、W3C SOAP仕様が信頼できる情報源です。
SOAPとは何か、そしてなぜ異なる扱いが必要なのか
ApidogはSOAPを、多様なプラットフォームとプログラミング言語が相互に通信できるようにするXMLベースの通信プロトコルである、シンプルオブジェクトアクセスプロトコルと説明しています。この一つのアイデアが、なぜ多くの企業が依然としてSOAPを運用しているのかを説明しています。Javaクライアントと.NETサービスは、互いの内部構造を気にすることなく、同じ契約を通じて通信できます。
テストする際には3つのプロパティが重要です。SOAPはメッセージのフォーマットにXMLを使用するため、すべてのリクエストとレスポンスは、バラバラのJSONブロブではなく、構造化されたドキュメントです。XML自体に馴染みがない場合は、MDNのXMLリファレンスが、読み書きする構文の確かな入門書となります。通常、プロトコルは他のものもサポートしていますが、HTTPまたはHTTPSを介して伝送されます。そして、構造化された信頼性の高い通信のためにW3C標準に従っており、これがメッセージの形式が厳格で検証ルールが確固たるものである理由です。
その厳格さこそが、SOAPエンドポイントがクロスプラットフォーム統合、レガシーからモダンへの橋渡し、およびWS-Securityを使用した暗号化された認証済みメッセージングによる安全なトランザクションのためにサービスを維持している理由です。また、RESTスタイルのリクエストをそのまま送信できない理由でもあります。正しいヘッダー、SOAPエンベロープでラップされたXMLボディ、そして返ってくるXMLを読み取る方法が必要です。エンベロープとそのボディがどのようにデータを運ぶかについて深く知りたい場合は、SOAP APIとXMLの解説をご覧ください。
始める前に
以下のすべてには、厳しい要件が1つあります。SOAPまたはWebServiceリクエストを送信するには、Apidogのバージョンが2.1.31以降である必要があります。古いビルドはこれをサポートしていません。Apidogを開き、バージョンを確認し、古い場合は更新してください。このガイドのその他の部分は、バージョン2.1.31以降を使用していることを前提としています。
まだApidogをお持ちでない場合は、Apidogをダウンロードして手順に従ってください。無料で試せます。クレジットカードは不要です。
また、ターゲットサービスの詳細も手元に用意しておくと良いでしょう。エンドポイントURL、呼び出したい操作名、そのパラメーターなどです。WSDLファイルをお持ちの場合は、このガイドの後半で直接インポートするため、近くに置いておいてください。
パスA: SOAPリクエストを手動で送信する
これは、エンドポイントがあり、呼び出したい操作を知っている場合のパスです。RESTリクエストでは必要としない3つの設定があり、それらを正しく設定することが作業のすべてです。
ステップ1: Content-Typeヘッダーを手動で設定する
SOAPリクエストは、独自のヘッダーを推測しません。Content-Typeを自分で設定する必要があり、有効な値は次の2つです。
text/xml; charset=utf-8application/soap+xml
どちらが正しいかはサービスによります。SOAP 1.1エンドポイントは通常text/xml; charset=utf-8を期待し、SOAP 1.2エンドポイントはしばしばapplication/soap+xmlを要求します。不明な場合は、WSDLまたはサービスドキュメントを確認し、最初の値がコンテンツタイプに関するエラーを返した場合は、もう一方に切り替えてください。送信する前に、リクエストのヘッダーセクションにヘッダーを追加します。
ステップ2: ボディフォーマットをXMLに設定し、エンベロープを貼り付ける
リクエストのボディフォーマットをxmlに設定し、SOAPエンベロープを貼り付けます。エンベロープは、名前空間宣言と、呼び出す操作およびその中にネストされたパラメータを保持するボディ要素を持つドキュメントです。
以下に、Apidogがドキュメントで使用しているものと同じ、公開されている数値を単語に変換するサービスに対する例を示します。操作はNumberToWordsで、ubiNumという1つのパラメータを取ります。
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="http://www.dataaccess.com/webservicesserver/">
<soap:Body>
<web:NumberToWords>
<web:ubiNum>1234</web:ubiNum>
</web:NumberToWords>
</soap:Body>
</soap:Envelope>
操作の名前空間は、サービスが期待するものと一致する必要があります。そのため、推測するのではなくWSDLから読み取ります。soap:Bodyは実際の呼び出しをラップし、web:NumberToWordsは操作であり、web:ubiNumは入力です。
ステップ3: XMLレスポンスを送信して読み取る
リクエストを送信します。レスポンスはXML形式で返され、そのボディにはレスポンス操作が含まれるSOAPエンベロープとして届きます。上記の呼び出しの場合、結果が内部にネストされたNumberToWordsResponseが返されます。
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<m:NumberToWordsResponse xmlns:m="http://www.dataaccess.com/webservicesserver/">
<m:NumberToWordsResult>one thousand two hundred and thirty four</m:NumberToWordsResult>
</m:NumberToWordsResponse>
</soap:Body>
</soap:Envelope>
レスポンスはリクエストを反映しています。操作名にはResponseサフィックスが付加され、値は結果要素に格納されます。この反映された部分に対してアサーションを実行します。エンベロープが返されたこと、NumberToWordsResponseノードが存在すること、そして結果が期待通りであることを確認します。webservice.apidog.ioにあるApidogの専用WebServiceドキュメントには、完全な設定リファレンスと、別の例が必要な場合の追加のサンプルエンベロープが掲載されています。
現実的なユースケースも同じ3つのステップに従います。NumberToWordsをレガシーな為替レートサービスのConvertCurrency操作に置き換え、fromCurrency、toCurrency、amountをネストされた要素として渡し、変換された数値をレスポンスエンベロープから読み取ります。または、注文ウェブサービスのGetOrderStatus操作を呼び出し、orderIdを渡し、返されたステータスノードに対してアサーションを実行します。仕組みは決して変わりません: ヘッダー、XMLボディ、送信、エンベロープの読み取りです。
パスB: WSDLをインポートしてエンドポイントを生成する
手動でエンベロープを入力するのは、1回の呼び出しには問題ありません。サービスが多数の操作を公開している場合は、WSDLに任せましょう。WSDLファイルは、すべての操作、その入力、およびサービスアドレスを記述しており、Apidogはこれらすべてを一度のインポートで読み取ります。
正確なクリックパスは次のとおりです。
- 設定に移動し、次にデータインポートを選択します。
WSDLを選択します。.wsdlまたは.xmlファイルをアップロードします。- Apidogがファイルから解析したAPIエンドポイントのプレビューを確認します。
Environmentsタブを開き、サービスアドレスが正しいことを確認します。Confirmをクリックします。インポートされた環境が自動的に作成されます。- 右上隅からインポートされた環境を選択します。
- リクエストを送信します。その環境からベースURLが自動的に適用されます。
このリストの2つのステップは、人々がスキップして後で後悔するものです。
ステップ5が重要なのは、WSDL内のサービスアドレスが、インポートされたすべてのリクエストがヒットするエンドポイントであるためです。もしそれがステージングホストを指していたり、WSDLの作成者が更新しなかったプレースホルダーURLだったりすると、リクエストは間違った場所に送信されます。Confirmをクリックする前に、Environmentsタブで確認してください。
ステップ7が重要なのは、ベースURLが自動生成された環境に存在するためです。右上隅からインポートされた環境を選択しない場合、リクエストにはベースアドレスがなく、失敗します。まず選択してから送信してください。
インポートが完了すると、各操作は自分でエンベロープを書かずに呼び出せるエンドポイントとして表示され、パスAとまったく同じようにXMLレスポンスに対してアサーションを実行します。プロジェクト全体を他のツールから移行する場合は、SOAPプロジェクトのインポートに関するガイドで、移行の最初から最後までを説明しています。
正直な制限が1つあります。WSDLインポートは、.wsdlファイルと.xmlファイルのファイルアップロードについて文書化されています。URLによるWSDLのインポートやコンテンツの貼り付けは文書化されていないため、URLフィールドを期待するのではなく、ファイルをアップロードしてください。
SoapUIからの移行
SOAPテストが現在SoapUIにある場合でも、白紙の状態から再構築する必要はありません。WSDLをエクスポートまたは保持し、パスBでApidogにインポートすれば、デザイン、モック、ドキュメントも実行できるワークスペース内で、呼び出し可能なエンドポイントとして同じ操作が得られます。得られる利点は統合です。SOAPサービス、RESTエンドポイント、テストシナリオを別々のツールに分散させるのではなく、1つのプロジェクトで保持できます。Apidog対SoapUIの比較では、何が引き継がれ、ワークフローがどこで異なるかを解説しています。
アサーションとバリエーション
単一の成功した呼び出しは、エンドポイントが稼働していることを証明します。テストはそれが正しいことを証明します。SOAPリクエストが返されたら、レスポンスエンベロープにアサーションを追加します。期待されるレスポンス操作ノードが存在することを確認し、結果要素を抽出し、契約が約束するものと照合してその値をチェックします。通貨サービスの場合、変換された金額が範囲内の数値であること、注文サービスの場合、ステータスが許可された値の1つであることをアサートします。
そこから、呼び出しを連鎖させる反復可能なテストシナリオを構築します。たとえば、注文を作成し、そのステータスを照会し、ステップ間で値を渡すなどです。Apidogでテストシナリオを作成する方法に関するチュートリアルでは、抽出された値を後のリクエストに接続する方法を示しています。このパターンはプロトコルに依存しないため、シナリオはSOAP呼び出しと周囲のRESTエンドポイントを混在させることができます。
セキュリティで保護されたエンドポイントの場合、SOAPは通常、暗号化された認証済みメッセージングにWS-Securityを使用します。そのセキュリティヘッダーは送信するSOAPエンベロープの一部であるため、操作とともにエンベロープのヘッダー内にwsseセキュリティブロックを追加します。送信の仕組みは変わりません。Content-Typeを設定し、セキュリティヘッダーを含む完全なエンベロープをXMLボディに入れ、送信します。
Apidog CLIでワークフローを自動化する
SOAPまたはWSDLでインポートされたリクエストがテストシナリオとして保存されると、Apidog CLIはそれらをコマンドラインから実行するため、パイプラインはプッシュごとにそれらをテストできます。Node.js v16以降でインストールし、認証してください。
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
WSDLインポートで作成された環境に対して、IDで保存されたシナリオを実行します。
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
ここで、-tはテストシナリオID、-eは環境ID、-rはレポーター（cli、html、またはjunit、複数指定の場合はカンマ区切り）です。正直な注意点が1つあります。ドキュメントには、ランナーが保存されたテストシナリオとスイートを実行すると記載されていますが、SOAPステップに基づいて構築されたシナリオがヘッドレスで実行されるかどうかは明記されていません。そのため、CLIはプロジェクトのHTTPシナリオ用として、またWSDLでインポートされたエンドポイントをCIで同期させるためのエンジンとして扱い、SOAP固有の実行を前提としないようにしてください。パイプラインへの組み込みについては、Apidog CLI CI/CDガイドで説明しています。
よくある質問
SOAPリクエストにはどのContent-Typeを使用すべきですか？ text/xml; charset=utf-8またはapplication/soap+xmlのいずれかです。どちらが正しいかはサービスによって異なります。SOAP 1.1エンドポイントは一般的に前者、SOAP 1.2エンドポイントは後者を期待します。リクエストヘッダーで手動で設定し、コンテンツタイプのエラーが発生した場合は、もう一方の値に切り替えてください。
ApidogでSOAPをテストするために有料プランが必要ですか？ 文書化された唯一の要件は、Apidogのバージョンが2.1.31以降であることです。SOAPまたはWSDLのサポートに関して、ティアゲートやセルフホストの制限は記載されていないため、現在のバージョンに更新すれば利用できます。
URLからWSDLをインポートできますか？ 文書化されているWSDLインポートは、.wsdlおよび.xmlファイルのアップロードを受け付けます。URLによるインポートやWSDLテキストの貼り付けは文書化されていないため、ファイルをアップロードしてください。インポート後、環境は自動的に作成され、送信する前に右上隅からそれを選択します。
同じプロジェクトでSOAPとREST APIの両方をテストするにはどうすればよいですか？ Apidogはそれらを1つのワークスペース内のリクエストタイプとして扱います。そのため、単一のプロジェクトでSOAP操作、RESTエンドポイント、さらにはGraphQL呼び出しも保持できます。GraphQLも検討している場合は、ApidogでのGraphQL APIテストに関するガイドがその側面をカバーしており、テストシナリオはそれらすべてにわたってリクエストを連鎖させることができます。
WSDLでインポートしたリクエストが間違ったサーバーに送信されます。何が起こったのですか？ 通常、2つの原因が考えられます。インポート時にEnvironmentsタブのサービスアドレスが間違っていて、確認せずにConfirmをクリックしたか、または右上隅からインポートされた環境を選択しなかったため、ベースURLが適用されなかったかのいずれかです。再インポートしてアドレスを確認し、送信する前に正しい環境がアクティブになっていることを確認してください。
まとめ
SOAPのテストは、別のレガシーツールを意味する必要はありません。Apidogでは、エンベロープを手動で送信するか（Content-Typeを設定し、ボディをxmlに設定し、エンベロープを貼り付け、XMLレスポンスを読み取る）、またはWSDLをインポートしてApidogにエンドポイントと環境を構築させることができます。どちらのパスも同じ結果にたどり着きます。つまり、ウェブサービスが依然としてその契約を尊重していることを繰り返し確認できます。バージョン2.1.31以降のApidogをダウンロードし、WSDLをインポートして、レガシーサービスを他のAPIサーフェスと同じテスト下に置いてください。