Bạn được cung cấp một endpoint SOAP. Có thể đó là một công cụ chuyển đổi tiền tệ cũ mà đội ngũ thanh toán của bạn vẫn phụ thuộc, hoặc một dịch vụ web quản lý đơn hàng mà đối tác đang chạy trên .NET. Bạn cần gọi nó, xác nhận nó trả về đúng như hợp đồng đã cam kết, và chứng minh nó vẫn hoạt động chính xác khi mã nguồn xung quanh thay đổi. Các công cụ REST không hoàn toàn phù hợp, vì SOAP yêu cầu một toàn bộ XML envelope, một Content-Type cụ thể và một WSDL mô tả mọi hoạt động.
Apidog xử lý các yêu cầu SOAP và WebService cùng với REST, GraphQL và gRPC, vì vậy bạn không cần một ứng dụng riêng biệt cho dịch vụ cũ duy nhất trong hệ thống của mình. Hướng dẫn này sẽ chỉ ra cả hai cách đã được tài liệu hóa: gửi yêu cầu SOAP thủ công và nhập WSDL để Apidog xây dựng môi trường và endpoint cho bạn. Nếu bạn muốn có cái nhìn tổng quan hơn về các giao thức trước, bài so sánh của chúng tôi về REST, GraphQL, gRPC và SOAP sẽ giải thích vị trí của từng loại. Để có định nghĩa chính thức về cấu trúc envelope, đặc tả W3C SOAP là nguồn đáng tin cậy.
SOAP là gì và tại sao nó cần cách xử lý khác biệt
Apidog mô tả SOAP là Giao thức Truy cập Đối tượng Đơn giản (Simple Object Access Protocol), một giao thức giao tiếp dựa trên XML cho phép các nền tảng và ngôn ngữ lập trình đa dạng giao tiếp với nhau. Ý tưởng này giải thích tại sao rất nhiều doanh nghiệp vẫn sử dụng nó. Một client Java và một dịch vụ .NET có thể giao tiếp thông qua cùng một hợp đồng mà không cần quan tâm đến chi tiết nội bộ của nhau.
Ba thuộc tính quan trọng khi bạn kiểm tra nó. SOAP sử dụng XML để định dạng tin nhắn, vì vậy mọi yêu cầu và phản hồi đều là một tài liệu có cấu trúc, không phải một khối JSON lỏng lẻo. Nếu XML là một lĩnh vực xa lạ, tài liệu tham khảo XML của MDN là một hướng dẫn vững chắc về cú pháp bạn sẽ đọc và viết. Nó thường truyền qua HTTP hoặc HTTPS, mặc dù giao thức này hỗ trợ các giao thức khác. Và nó tuân theo các tiêu chuẩn W3C để giao tiếp có cấu trúc, đáng tin cậy, đó là lý do tại sao hình dạng tin nhắn nghiêm ngặt và các quy tắc xác thực chặt chẽ.
Sự nghiêm ngặt đó là lý do tại sao các endpoint SOAP vẫn được sử dụng cho tích hợp đa nền tảng, cầu nối từ hệ thống cũ sang hiện đại và các giao dịch an toàn sử dụng WS-Security cho việc nhắn tin được mã hóa, xác thực. Đó cũng là lý do tại sao bạn không thể chỉ gửi một yêu cầu kiểu REST đến nó. Bạn cần đúng header, một XML body được gói trong một SOAP envelope, và một cách để đọc XML trả về. Nếu bạn muốn tìm hiểu sâu hơn về cách envelope và body của nó mang dữ liệu, hãy xem bài phân tích của chúng tôi về SOAP API và XML.
Trước khi bạn bắt đầu
Có một yêu cầu bắt buộc cho tất cả những điều dưới đây. Để gửi yêu cầu SOAP hoặc WebService, Apidog cần có phiên bản 2.1.31 trở lên. Các bản dựng cũ hơn không hỗ trợ điều này. Mở Apidog, kiểm tra phiên bản của bạn và cập nhật nếu bạn đang dùng phiên bản cũ hơn. Mọi thứ khác trong hướng dẫn này đều giả định bạn đang sử dụng phiên bản 2.1.31 trở lên.
Nếu bạn chưa có Apidog, hãy tải xuống Apidog và làm theo. Dùng thử miễn phí, không yêu cầu thẻ tín dụng.
Bạn cũng sẽ muốn có sẵn thông tin chi tiết về dịch vụ mục tiêu của mình: URL endpoint, tên hoạt động bạn muốn gọi và các tham số của nó. Nếu bạn có tệp WSDL, hãy giữ nó ở gần, vì nửa sau của hướng dẫn này sẽ nhập trực tiếp nó.
Cách A: gửi yêu cầu SOAP thủ công
Đây là cách bạn thực hiện khi có một endpoint và biết hoạt động bạn muốn gọi. Có ba điều bạn cần thiết lập mà yêu cầu REST không cần, và thiết lập đúng chúng là toàn bộ công việc.
Bước 1: Thiết lập thủ công header Content-Type
Các yêu cầu SOAP không tự suy ra header của chúng. Bạn tự thiết lập Content-Type, và có hai giá trị hợp lệ:
text/xml; charset=utf-8application/soap+xml
Giá trị nào đúng phụ thuộc vào dịch vụ. Các endpoint SOAP 1.1 thường mong đợi text/xml; charset=utf-8, trong khi các endpoint SOAP 1.2 thường muốn application/soap+xml. Nếu bạn không chắc chắn, hãy kiểm tra WSDL hoặc tài liệu dịch vụ, và nếu giá trị đầu tiên trả về lỗi về content type, hãy chuyển sang giá trị kia. Thêm header vào phần Headers của yêu cầu trước khi bạn gửi.
Bước 2: Đặt định dạng body thành XML và dán envelope
Đặt định dạng Body của yêu cầu thành xml, sau đó dán SOAP envelope. Envelope là một tài liệu với các khai báo namespace và một phần tử Body chứa hoạt động bạn đang gọi, cùng với bất kỳ tham số nào được lồng bên trong nó.
Dưới đây là một ví dụ đã thực hiện với dịch vụ công cộng chuyển đổi số thành chữ, có hình dạng tương tự như Apidog sử dụng trong tài liệu của mình. Hoạt động là NumberToWords và nó nhận một tham số, ubiNum:
<?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>
Namespace trên hoạt động phải khớp với những gì dịch vụ mong đợi, đó là lý do tại sao bạn đọc nó từ WSDL thay vì đoán. soap:Body gói gọn cuộc gọi thực tế; web:NumberToWords là hoạt động; web:ubiNum là đầu vào.
Bước 3: Gửi và đọc phản hồi XML
Gửi yêu cầu. Phản hồi sẽ trả về dưới dạng XML, là một SOAP envelope mà Body của nó chứa hoạt động phản hồi. Đối với cuộc gọi ở trên, bạn sẽ nhận được một NumberToWordsResponse với kết quả được lồng bên trong:
<?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>
Phản hồi phản ánh yêu cầu: tên hoạt động có thêm hậu tố Response, và giá trị nằm trong một phần tử kết quả. Sự phản ánh đó là điều bạn kiểm tra. Bạn xác nhận envelope đã được trả về, nút NumberToWordsResponse tồn tại và kết quả khớp với những gì bạn mong đợi. Tài liệu WebService chuyên dụng của Apidog tại webservice.apidog.io cung cấp tài liệu cấu hình đầy đủ và thêm các envelope mẫu nếu bạn muốn xem ví dụ thực tế thứ hai.
Một trường hợp sử dụng thực tế cũng tuân theo ba bước tương tự. Thay thế NumberToWords bằng một hoạt động ConvertCurrency trên một dịch vụ tỷ giá hối đoái cũ, truyền fromCurrency, toCurrency và amount dưới dạng các phần tử lồng nhau, sau đó đọc số đã chuyển đổi từ response envelope. Hoặc gọi hoạt động GetOrderStatus trên một dịch vụ web đặt hàng, truyền orderId và kiểm tra nút trạng thái được trả về. Các cơ chế không bao giờ thay đổi: header, xml body, gửi, đọc envelope.
Cách B: nhập WSDL để tạo các endpoint
Gõ envelope thủ công thì ổn với một lần gọi. Khi một dịch vụ hiển thị hàng chục hoạt động, hãy để WSDL làm công việc đó. Một tệp WSDL mô tả mọi hoạt động, đầu vào của nó và địa chỉ dịch vụ, và Apidog đọc tất cả những điều đó trong một lần nhập.
Đây là các bước thực hiện chi tiết:
- Đi tới Cài đặt (Settings), sau đó chọn Nhập dữ liệu (Import Data).
- Chọn
WSDL. - Tải lên tệp
.wsdlhoặc.xmlcủa bạn. - Xem lại bản xem trước các endpoint API mà Apidog đã phân tích từ tệp.
- Mở tab
Environmentsvà xác minh địa chỉ dịch vụ là chính xác. - Nhấp vào
Xác nhận (Confirm). Môi trường đã nhập sẽ được tạo tự động. - Chọn môi trường đã nhập từ góc trên bên phải.
- Gửi yêu cầu. URL cơ sở (Base URL) được áp dụng tự động từ môi trường đó.
Hai bước trong danh sách đó là những bước mà mọi người thường bỏ qua và sau đó hối tiếc.
Bước 5 quan trọng vì địa chỉ dịch vụ trong WSDL là endpoint mà mọi yêu cầu được nhập sẽ gửi đến. Nếu nó trỏ đến một host staging, hoặc một URL giữ chỗ mà tác giả WSDL chưa bao giờ cập nhật, các yêu cầu của bạn sẽ đi sai chỗ. Hãy kiểm tra nó trong tab Environments trước khi bạn nhấp vào Xác nhận (Confirm), không phải sau đó.
Bước 7 quan trọng vì Base URL nằm trong môi trường được tạo tự động đó. Nếu bạn không chọn môi trường đã nhập từ góc trên bên phải, các yêu cầu của bạn sẽ không có địa chỉ cơ sở và chúng sẽ thất bại. Hãy chọn nó trước, sau đó gửi.
Sau khi bạn đã nhập, mỗi hoạt động sẽ hiển thị dưới dạng một endpoint mà bạn có thể gọi mà không cần tự viết envelope, và bạn kiểm tra phản hồi XML chính xác như trong Cách A. Nếu bạn đang chuyển toàn bộ dự án từ một công cụ khác, hướng dẫn của chúng tôi về nhập dự án SOAP sẽ bao gồm việc di chuyển từ đầu đến cuối.
Lưu ý một hạn chế thực tế: việc nhập WSDL được tài liệu hóa cho việc tải lên các tệp .wsdl và .xml. Việc nhập WSDL bằng URL hoặc bằng cách dán nội dung của nó không được tài liệu hóa, vì vậy hãy tải lên tệp thay vì mong đợi một trường URL.
Chuyển từ SoapUI
Nếu các bài kiểm tra SOAP của bạn hiện đang nằm trong SoapUI, bạn không cần phải xây dựng lại chúng từ đầu. Xuất hoặc giữ WSDL của bạn, nhập nó vào Apidog bằng Cách B, và bạn sẽ có được các hoạt động tương tự dưới dạng các endpoint có thể gọi trong một không gian làm việc cũng thực hiện thiết kế, mocking và tài liệu hóa. Lợi ích là hợp nhất: một dự án chứa dịch vụ SOAP của bạn, các endpoint REST của bạn và các kịch bản kiểm tra của bạn thay vì phân tán chúng trên các công cụ riêng biệt. Bài so sánh Apidog với SoapUI của chúng tôi sẽ hướng dẫn bạn những gì có thể chuyển đổi và nơi các quy trình làm việc khác nhau.
Xác nhận và các biến thể
Một cuộc gọi thành công duy nhất chứng minh endpoint còn hoạt động. Một bài kiểm tra chứng minh nó đúng. Sau khi yêu cầu SOAP của bạn trả về, hãy thêm các xác nhận vào response envelope: xác nhận rằng nút hoạt động phản hồi mong muốn có mặt, trích xuất phần tử kết quả và kiểm tra giá trị của nó so với những gì hợp đồng đã hứa. Đối với dịch vụ tiền tệ, bạn xác nhận số tiền đã chuyển đổi là một số trong phạm vi; đối với dịch vụ đặt hàng, bạn xác nhận trạng thái là một trong các giá trị được phép.
Từ đó bạn xây dựng một kịch bản kiểm tra lặp lại, chuỗi các cuộc gọi, ví dụ: tạo một đơn hàng, sau đó truy vấn trạng thái của nó, truyền giá trị giữa các bước. Hướng dẫn của chúng tôi về viết kịch bản kiểm tra với Apidog cho thấy cách nối các giá trị được trích xuất vào các yêu cầu sau. Mẫu này không phụ thuộc vào giao thức, vì vậy một kịch bản có thể kết hợp một cuộc gọi SOAP với các endpoint REST xung quanh nó.
Đối với các endpoint được bảo mật, SOAP thường sử dụng WS-Security cho việc nhắn tin được mã hóa, xác thực. Header bảo mật đó là một phần của SOAP envelope bạn gửi, vì vậy bạn thêm khối bảo mật wsse vào bên trong header của envelope cùng với hoạt động của bạn. Cơ chế gửi vẫn như cũ: đặt Content-Type, đặt toàn bộ envelope bao gồm header bảo mật vào xml body, và gửi.
Tự động hóa quy trình làm việc với Apidog CLI
Sau khi các yêu cầu SOAP hoặc WSDL đã nhập của bạn được lưu dưới dạng kịch bản kiểm tra, Apidog CLI sẽ chạy chúng từ dòng lệnh để một pipeline có thể thực thi chúng trên mỗi lần đẩy (push). Cài đặt nó với Node.js v16 trở lên, sau đó xác thực:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Chạy một kịch bản đã lưu bằng ID, với môi trường mà WSDL của bạn đã tạo:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Ở đây -t là ID kịch bản kiểm tra, -e là ID môi trường, và -r là bộ báo cáo (cli, html, hoặc junit, được phân tách bằng dấu phẩy cho nhiều loại). Một lưu ý thành thật: tài liệu xác nhận trình chạy thực thi các kịch bản kiểm tra và bộ kiểm tra đã lưu, nhưng chúng không nói liệu các kịch bản được xây dựng trên các bước SOAP có chạy không đầu (headless) hay không, vì vậy hãy coi CLI là công cụ của bạn cho các kịch bản HTTP của dự án và để giữ các endpoint đã nhập WSDL đồng bộ trong CI thay vì giả định thực thi cụ thể cho SOAP. Việc kết nối nó vào một pipeline được đề cập trong hướng dẫn CI/CD của Apidog CLI của chúng tôi.
Câu hỏi thường gặp
Tôi nên sử dụng Content-Type nào cho yêu cầu SOAP? Hoặc text/xml; charset=utf-8 hoặc application/soap+xml. Loại đúng phụ thuộc vào dịch vụ: các endpoint SOAP 1.1 thường mong đợi loại đầu tiên, các endpoint SOAP 1.2 loại thứ hai. Đặt thủ công trong request headers, và nếu bạn gặp lỗi content-type, hãy chuyển sang giá trị khác.
Tôi có cần gói trả phí để kiểm tra SOAP trong Apidog không? Yêu cầu duy nhất được ghi trong tài liệu là Apidog phải có phiên bản 2.1.31 trở lên. Không có giới hạn cấp bậc hoặc hạn chế self-hosted nào được nêu cho hỗ trợ SOAP hoặc WSDL, vì vậy hãy cập nhật lên phiên bản hiện tại và bạn đã sẵn sàng.
Tôi có thể nhập WSDL từ một URL không? Việc nhập WSDL được ghi trong tài liệu chấp nhận tải lên các tệp .wsdl và .xml. Việc nhập bằng URL hoặc bằng cách dán văn bản WSDL không được ghi trong tài liệu, vì vậy hãy tải lên tệp. Sau khi nhập, môi trường sẽ được tạo tự động và bạn chọn nó từ góc trên bên phải trước khi gửi.
Làm cách nào để kiểm tra cả SOAP và REST API trong cùng một dự án? Apidog xử lý chúng như các loại yêu cầu trong một không gian làm việc, vì vậy một dự án duy nhất có thể chứa các hoạt động SOAP bên cạnh các endpoint REST và thậm chí cả các cuộc gọi GraphQL. Nếu GraphQL cũng nằm trong kế hoạch của bạn, hướng dẫn của chúng tôi về kiểm tra GraphQL API trong Apidog sẽ bao gồm khía cạnh đó, và một kịch bản kiểm tra có thể chuỗi các yêu cầu trên tất cả chúng.
Các yêu cầu WSDL đã nhập của tôi gửi đến máy chủ sai. Điều gì đã xảy ra? Có hai nguyên nhân thường gặp. Hoặc địa chỉ dịch vụ trong tab Environments đã sai tại thời điểm nhập và bạn đã nhấp vào Xác nhận (Confirm) mà không kiểm tra nó, hoặc bạn chưa chọn môi trường đã nhập từ góc trên bên phải, vì vậy không có Base URL nào được áp dụng. Hãy nhập lại và xác minh địa chỉ, sau đó đảm bảo môi trường đúng đang hoạt động trước khi bạn gửi.
Tóm lại
Kiểm thử SOAP không nhất thiết phải dùng một công cụ cũ riêng biệt. Trong Apidog, bạn có thể gửi envelope thủ công (đặt Content-Type, đặt body thành xml, dán envelope, đọc phản hồi XML) hoặc nhập WSDL và để Apidog xây dựng các endpoint và môi trường cho bạn. Cả hai cách đều dẫn đến cùng một kết quả: một kiểm tra lặp lại rằng dịch vụ web của bạn vẫn tuân thủ hợp đồng của nó. Tải xuống Apidog phiên bản 2.1.31 trở lên, nhập WSDL của bạn và đưa các dịch vụ cũ của bạn vào cùng một bài kiểm tra với phần còn lại của bề mặt API của bạn.