cXML という電子商取引の トランザクションを支える プロトコルと向きあっている話

Kaigi on Rails 2024 での発表資料です

https://kaigionrails.org/2024/talks/phigasui/

Transcript

1. cXML という電子商取引の トランザクションを支える プロトコルと向きあっている話 Kaigi on Rails 2024 Day1 - 10.25 (Fri.) Hall Blue Leaner Technologies Inc. @phigasui / がーしー
2. 2 cXMLって聞いたことありますか?
3. 3 cXML とは cXML とは • 電子商取引(EC)に関するシステム間で 一貫したドキュメントでの通信を目的としたプロトコル ◦ 例「注文ではこのフォーマットでリクエストしてください」 というのが定義されている ここで知っておいてほしいこと • システム間連携開発をやるよ • 共通化されたプロトコルがあるよ
4. 4 伝えたいこと • cXML というニッチだけど面白い技術があるよ ◦ おもしろい仕様の一例を紹介 • システム間の連携開発を通した学び ◦ 実際におきた大変だったこと ◦ 乗り越えるためにやっていること
5. 5 目次 • なぜ cXML と向きあっているのか • cXML とパンチアウト連携 • 実際に発生した問題とそこからの学び
6. 6 目次 • なぜ cXML と向きあっているのか • cXML とパンチアウト連携 • 実際に発生した問題とそこからの学び
7. 7 なぜ cXML と向きあっているのか A社 EC B社 EC C社 EC A社 EC B社 EC C社 EC 購買システム: 多様な取引先からの購買業務を一元管理 それぞれの EC サイトで 登録・ログインが必要 購買システムにだけ 登録・ログイン
8. 8 なぜ cXML と向きあっているのか • 複数の EC サイトと連携する必要がある • 各接続先の API で連携しシステムを構築 ↓ 電子商取引(EC)では cXML という プロトコルが使われている A社 EC B社 EC C社 EC
9. 9 目次 • なぜ cXML と向きあっているのか • cXML とパンチアウト連携 • 実際に発生した問題とそこからの学び
10. 10 cXML とパンチアウト連携 cXML とは commerce eXtensible Markup Language の略 通信のモデルとデータ構造を定義している 連携を楽にするため、パンチアウト連携という 仕組みが用意されている
11. 11 cXML とパンチアウト連携 パンチアウト連携 • EC の機能を使いながら購買の情報を連携 ECサイト ③商品をカートに追加 購買システム ⑤購買の次ステップ (購買承認依頼など) リーニャー商品ページ チェックアウト 購買申請する ①アクセス ②チェックイン (ECサイトに自動ログイン) ④チェックアウト (カート情報を購買システムへ持ち帰る) 購買システム リーナーECで商品を探す
12. 12 cXML とパンチアウト連携 パンチアウト連携 • EC の機能を使いながら購買の情報を連携 ECサイト ③商品をカートに追加 購買システム ⑤購買の次ステップ (購買承認依頼など) リーニャー商品ページ チェックアウト 購買申請する ①アクセス ②チェックイン (購買システムに自動ログイン) ④チェックアウト (カート情報を購買システムへ持ち帰る) 購買システム リーナーECで商品を探す
13. 13 cXML とパンチアウト連携 パンチアウト連携 • EC の機能を使いながら購買の情報を連携 購買システム ⑤購買の次ステップ (購買承認依頼など) 購買申請する ①アクセス ④チェックアウト (カート情報を購買システムへ持ち帰る) 購買システム リーナーECで商品を探す ECサイト ③商品をカートに追加 リーニャー商品ページ チェックアウト ②チェックイン (ECサイトに自動ログイン)
14. 14 cXML とパンチアウト連携 パンチアウト連携 • EC の機能を使いながら購買の情報を連携 購買システム ⑤購買の次ステップ (購買承認依頼など) 購買申請する ①アクセス 購買システム リーナーECで商品を探す ECサイト ③商品をカートに追加 リーニャー商品ページ チェックアウト ②チェックイン (ECサイトに自動ログイン) ④チェックアウト (カート情報を購買システムへ持ち帰る)
15. 15 cXML とパンチアウト連携 パンチアウト連携 • EC の機能を使いながら購買の情報を連携 ECサイト ③商品をカートに追加 購買システム ⑤購買の次ステップ (購買承認依頼など) リーニャー商品ページ チェックアウト 購買申請する ①アクセス ②チェックイン (ECサイトに自動ログイン) ④チェックアウト (カート情報を購買システムへ持ち帰る) 購買システム リーナーECで商品を探す ？ ？
16. 16 cXML とパンチアウト連携 パンチアウト連携 • EC の機能を使いながら購買の情報を連携 購買システム ⑤購買の次ステップ (購買承認依頼など) 購買申請する ①アクセス ④チェックアウト (カート情報を購買システムへ持ち帰る) 購買システム リーナーECで商品を探す ECサイト ③商品をカートに追加 リーニャー商品ページ チェックアウト ②チェックイン (ECサイトに自動ログイン)
17. 17 cXML とパンチアウト連携 パンチアウト開始のリクエスト EC サイトでユーザー登録・ログインする ための情報 購買システムに戻る時に対象のカートを 特定するための情報 カート情報の送信先 購買システムに戻る時に POSTしてもらうエンドポイント
18. 18 cXML とパンチアウト連携 パンチアウト連携 • EC の機能を使いながら購買の情報を連携 購買システム ⑤購買の次ステップ (購買承認依頼など) 購買申請する ①アクセス 購買システム リーナーECで商品を探す ECサイト ③商品をカートに追加 リーニャー商品ページ チェックアウト ②チェックイン (ECサイトに自動ログイン) ④チェックアウト (カート情報を購買システムへ持ち帰る)
19. 19 cXML とパンチアウト連携 カート情報の連携 購買システムに戻る時に対象のカートを 特定するための情報 パンチアウト開始時に連携したBuyerCookie
20. 20 cXML とパンチアウト連携 cXML のリファレンスに600ページに渡って ほかにもたくさんの仕様が定義されている • 注文のリクエスト • 注文受理、キャンセルのリクエスト • 出荷の情報 などなど 引用:「cXML Reference Guide」 https://xml.cxml.org/current/cXMLReferenceGuide_ja.pdf
21. 21 cXML仕様 実装すればどんな EC サイトとも連携できる!!
22. 22 cXML仕様 実装すればどんな EC サイトとも連携できる!! → ほんとうか?
23. 23 目次 • なぜ cXML と向きあっているのか • cXML とパンチアウト連携 • 実際に発生した問題とそこからの学び
24. 24 ここまでのおさらい • 複数の EC サイトとプロダクト間の連携が必要になる • cXML というプロトコルで共通の仕様が定義されている ◦ この仕様に則れば汎用的に連携できる ◦ ただし、仕様は膨大
25. 25 実際に発生した問題 • 各接続先で異なる cXML の仕様がある • いろいろな制約がある ◦ 物理的な制限や各 EC での特殊な仕様 • そもそも、cXML の仕様すべて対応できているわけではない ◦ 我々のプロダクトも、連携先も...
26. 26 実際に発生した問題 • 各接続先で異なる cXML の仕様がある • いろいろな制約がある ◦ 物理的な制限や各 EC での特殊な仕様 • そもそも、cXML の仕様すべて対応できているわけではない ◦ 我々のプロダクトも、連携先も...
27. 27 実際に発生した問題 - cXML の仕様のちがいの例 cXML では Extrinsic という要素が定義されている 引用:「cXML Reference Guide」 https://xml.cxml.org/current/cXMLReferenceGuide_ja.pdf 日本語訳: 「非本質的な、付帯的な」
28. 28 実際に発生した問題 - cXML の仕様のちがいの例 各 EC 向けにサブクラスを実装して仕様のちがいを吸収 リクエストにフックして実装する メソッドをオーバーライド
29. 29 実際に発生した問題 - cXML の仕様のちがいの例 仕様のちがいをのりこえていくために • 連携先との仕様の認識すりあわせ ◦ リーナーで定義した cXML 仕様をベースに調整
30. 30 実際に発生した問題 • 各接続先で異なる cXML の仕様がある • いろいろな制約がある ◦ 物理的な制限や各 EC での特殊な仕様 • そもそも、cXML の仕様すべて対応できているわけではない ◦ 我々のプロダクトも、連携先も...
31. 31 実際に発生した問題 - 物理的な制約の例 • cXML 各要素、属性の文字数までは決められない ◦ 各 EC サイトで文字数の上限が異なるため注意が必要 • とくに厄介なのが配送先の文字数 ◦ 最終的には伝票に印字されるため物理的な限界がある
32. 32 実際に発生した問題 - 物理的な制約の例 実際にリーナー宛に届いた(届かなかった)商品の配送伝票 • 謎の文字列入ってる • お届け先の欄からはみ出てる • Leaner Tec で途切れてる 宛先不明となり営業所止めに 担当者名
33. 33 実際に発生した問題 - 物理的な制約の例 仕様外の制約をのりこえていくために • 連携のシナリオテスト ◦ 連携先とそれぞれ確認が必要なケースを洗い出す ▪ 例) 各税率の商品、情報が連携されるタイミング 動的情報の最大文字数パターン、などなど ◦ これで事前に文字数制限をキャッチできたこともあった テストケースのドキュメント
34. 34 実際に発生した問題 • 各接続先で異なる cXML の仕様がある • いろいろな制約がある ◦ 物理的な制限や各 EC での特殊な仕様 • そもそも、cXML の仕様すべて対応できているわけではない ◦ 我々のプロダクトも、連携先も...
35. 35 実際に発生した問題 - 対応できていなかった cXML 仕様の例 • 同一商品を複数個注文した内の一部キャンセル ◦ 例: ボールペンを8本注文した内、2本だけ在庫切れでキャンセル
36. 36 実際に発生した問題 - 対応できていなかった cXML 仕様の例 • EC サイトから購買システムへ送信される注文の結果 例. キャンセルされた時の cXML 意図しない type の場合 処理方法が不明なため Error を 通知
37. 37 実際に発生した問題 - 対応できていなかった cXML 仕様の例 • 通知されたエラーでは type が nil になっていた ◦ 幸いイベントログを取得している 😌 ◦ cXML のログを見てみると... ConfirmationStatus はいつも 1つ ConfirmationStatus が 2つ？
38. 38 実際に発生した問題 - 対応できていなかった cXML 仕様の例 • ConfirmationStatus が2つある時の cxml-ruby (gem) のパース結果 ◦ たしかに type が nil ◦ そもそも confirmation_status 複数のため Array になりそうだが？
39. 39 実際に発生した問題 - 対応できていなかった cXML 仕様の例 • cxml-ruby の ConfirmationStatus の親要素の定義を確認 ◦ 複数受け取られる定義ではない 🙂 複数要素OKな時は別の定義の 仕方が必要
40. 40 実際に発生した問題 - 対応できていなかった cXML 仕様の例 • cXML のリファレンスを見ると 購買システム側でも想定して実装してなかったが そもそも cxml-ruby の gem でも想定されていなかった 😂 引用:「cXML Reference Guide」 https://xml.cxml.org/current/cXMLReferenceGuide_ja.pdf
41. 41 実際に発生した問題 - 対応できていなかった cXML 仕様の例 これらのことからの学び • 外部イベントのロギングにより再現と原因の究明ができた ◦ 連携先からなにが送られてきたか分からなくなってしまうためイベントログ大事 • 連携先との仕様調整でイレギュラーケースをいかに把握するか ◦ 今やっていること ▪ 定期的な同期コミュニケーションをとる ▪ これまでに発見したイレギュラーケースを仕様にまとめる
42. 42 cXML仕様 実装すればどんな EC サイトとも連携できる!! → ほんとうか?
43. 43 cXML仕様 実装すればどんな EC サイトとも連携できる!! → ほんとうか? → 楽にはなるが、安心はできない 😂
44. 44 まとめ • cXML はおもしろい ◦ イレギュラーケースにどう向きあうかは腕の見せどころ • システム間連携ではエラーの再現ができるようにする ◦ 外部の情報はログがないと再現や復旧が難しい • 連携先との密なコミュニケーションが大事 ◦ 全てを仕様書に表わすことは難しい ◦ 細かい仕様のキャッチアップができる状態をつくる必要がある
45. 45 おまけ
46. 46 自己紹介 • がーしー / @phigasui ◦ Kaigi on Rails 2024 中は「がーしーえっくすえむえる」 • 株式会社Leaner Technologies • プロダクトエンジニア
47. 47 なぜ cXML と向きあっているのか 調達のスタンダードを 刷新し続ける
48. 48 Event
49. 49 cXML とパンチアウト連携 パンチアウトトランザクションの流れ パンチアウト開始 リクエスト パンチアウト開始 リクエスト パンチアウト 開始URL パンチアウト 開始URL パンチアウト開始URL へアクセス 商品 カート 追加 チェック アウト 注文 情報 注文 情報 購買 システム EC サイト
50. 50 cXML とパンチアウト連携 パンチアウトトランザクションの流れ パンチアウト開始 リクエスト パンチアウト開始 リクエスト パンチアウト 開始URL パンチアウト 開始URL パンチアウト開始URL へアクセス 商品 カート 追加 チェック アウト 注文 情報 注文 情報 購買 システム EC サイト
51. 51 cXML とパンチアウト連携 パンチアウトトランザクションの流れ パンチアウト開始 リクエスト パンチアウト開始 リクエスト パンチアウト 開始URL パンチアウト 開始URL パンチアウト開始URL へアクセス 商品 カート 追加 チェック アウト 注文 情報 注文 情報 購買 システム EC サイト
52. 52 cXML とパンチアウト連携 注文以降のリクエストの流れ 購買 システム EC サイト 最終承認 注文 注文確認 出荷通知 購買申請
53. 53 cXML とパンチアウト連携 注文以降のリクエストの流れ 購買 システム EC サイト 最終承認 注文 注文確認 出荷通知 購買申請
54. 54 cXML とパンチアウト連携 注文のリクエスト OrderRequest • 注文する商品情報(商品識別子や金額)、配送先 を送って注文を要求する • ItemOuts は PunchOutOrderMessage の ItemIns と同じ
55. 55 cXML とパンチアウト連携 注文以降のリクエストの流れ 購買 システム EC サイト 最終承認 注文 注文確認 出荷通知 購買申請
56. 56 cXML とパンチアウト連携 注文確認のリクエスト ConfirmationRequest • 注文を受けて一定時間後にリクエストが来る • 注文を確定したり、キャンセル、金額の変更 があればその情報が連携されたりする • 複数回届く場合もある
57. 57 Rails アプリケーションでの実装 Controller ServiceClass ParserClass GatewayClass Rails は API モード • Gateway で EC サイトへのリクエスト ◦ 各 EC 向けのサブクラスで仕様の差分を実装 • Parser で必要な情報にアクセスしやすく • cxml-ruby という Gem で cXML の 操作やバリデーション cxml-ruby
58. 58 Rails アプリケーションでの実装 cxml-ruby • cXML のバリデーション • cXML のパース • Hash から cXML への変換 各要素のクラスがあり 存在する属性と子要素が定義されている