APIで叶えるシステム連携 #mauticon

Mauticには外部システム連携のための方法として、REST API、Webhook、プラグインシステムがサポートされているため、システム間のデータ同期や何らかのアクションをトリガーとした処理をシームレスに行うことが可能です。
サイボウズ社が提供するCRM「Kintone」を例に、APIを用いたMautic連携についてデモを交えてご紹介します。

https://mauticon.mautic.org/

Transcript

1. Mautic Conference Global 2022 APIͰ׎͑Δ γεςϜ࿈ܞ ΞΫΠΞδϟύϯ߹ಉձࣾ ؙࢁͻ͔Δ
2. Profile 1991೥10݄29೔ ੜ·Ε ಠཱܥιϑτ΢ΣΞ։ൃձࣾͰιϑτ΢ΣΞΤϯδχΞ ͷͪΤόϯδΣϦετͱͯ͠ϓϩμΫτͷܒ໤׆ಈ 2019೥8݄ ΞΫΠΞʹδϣΠϯ ΢ΣϒαΠτͷίϯςϯπͷ ٕज़຋༁΍ϩʔΧϥΠζΛ୲౰ Ruby / Rails / Web API / Docker / AWS ϥʔϝϯ / εΠʔπ / Ωϟϯϓ൧ / ొࢁ ΞΫΠΞδϟύϯ ؙࢁͻ͔Δ ςΫχΧϧτϥϯεϨʔλʔ
3. – MauticͰ͸ɺsalesforce΍TwitterͳͲଞγεςϜͱ࿈ܞ͢ΔͨΊͷϓϥάΠϯ͕͍͔ͭ͘ඪ४ Ͱ༻ҙ͞Ε͓ͯΓɺϊʔίʔυͰ؆୯ʹγεςϜ࿈ܞ͕ߦ͑·͢ɻ 
 – ͔͠͠ɺϓϥάΠϯ͕༻ҙ͞Ε͍ͯͳ͍৔߹͸Ͳ͏͢Ε͹ྑ͍Ͱ͠ΐ͏͔ʁ·ͨɺ༻ҙ͞Ε ͍ͯΔϓϥάΠϯͰ͸ཁ݅Λຬͨͤͳ͍৔߹Ͳ͏͢Ε͹ྑ͍Ͱ͠ΐ͏͔ʁ MauticͷγεςϜ࿈ܞ
4. – MauticͰ༻ҙ͞Ε͍ͯΔ REST API ΍ Webhook Λ׆༻ͯ͠γεςϜ࿈ܞ͕ߦ͑·͢ɻZapier ͳͲͷλεΫࣗಈԽπʔϧ΋ɺཪଆͰ͸REST APIɺWebhook͕ݺͼग़͞Ε͍ͯ·͢ɻ 
 – ࿈ܞ͍ͨ͠γεςϜଆʹ΋APIͷޱ͕༻ҙ͞Ε͍ͯΕ͹ɺϓϩάϥϚϒϧʹࣗಈԽϑϩʔΛ ૊Ή͜ͱ͕Ͱ͖·͢ɻ 
 – ͦΜͳMauticͷAPIͷ֓ཁ΍࢖͍ํɺ࿈ܞσϞΛ͝঺հ͠·͢ɻ MauticͷγεςϜ࿈ܞ
5. ຊ೔ͷτϐοΫ – MauticͷREST APIʹ͍ͭͯ – REST APIͷ࢖͍ํ – OAuthʹΑΔೝূೝՄ – APIϦΫΤετΛςετ͢Δ – MauticͱKintoneΛ࿈ܞ͢Δ
6. MauticͷREST API
7. – Mautic͸RESTܗࣜͷWeb API (REST API)͕ఏڙ͞Ε͍ͯ·͢ɻ – PHPϥΠϒϥϦ(mautic/api-library)͕ެ։͞Ε͍ͯ·͢ɻ – JSONܗࣜͰϨεϙϯεΛग़ྗ͠·͢ɻ 
 – ΤϯτϦϙΠϯτɿhttps://your-mautic.com/api 
 – ରԠ͍ͯ͠ΔೝূೝՄํࣜ – Basicೝূ – OAuth 2 (OAuth 1͸Mautic 4ܥͰഇࢭ) MauticͷREST APIͱ͸
8. – Mauticͷ؅ཧը໘Ͱߦ͑Δ͜ͱͷ΄ͱΜͲ͕APIܦ༝Ͱ΋ߦ͑·͢ɻ ๛෋ͳΤϯυϙΠϯτ Assets Campaigns Categories Companies Contacts Data Dynamic Content Emails Fields Files Forms Marketing Messages Notes Nortifications Pages Point Actions Point Triggers Roles Segments Text messages Stages Tags Themes Tweets Users Webhooks
9. REST APIͷ࢖͍ํ
10. – [ωδϚʔΫ] > [ઃఆ] > [APIઃఆ] ͔ΒɺAPIؔ࿈ͷઃఆ͕ߦ͑·͢ɻ APIઃఆ
11. – BasicೝূͰ͋Ε͹ɺઌड़ͷAPIઃఆը໘ͷ [BasicೝূΛ༗ޮʹ͢Δ] ϑϥάΛ༗ޮԽ͢Δͩ ͚Ͱ͙͢ʹར༻Ͱ͖·͢ɻ – ࢿ֨৘ใ͸MauticͷϩάΠϯϢʔβʔͷϢʔβʔ໊/ύεϫʔυΛ࢖༻͠·͢ɻ BasicೝূʹΑΔAPIϦΫΤετ
12. OAuthʹΑΔೝূೝՄ
13. – RFC 6749Ͱఆٛ͞ΕͨೝՄϑϨʔϜϫʔΫͰ͢ɻ – ΤϯυϢʔβʔ͸ɺID/ύεϫʔυΛαʔυύʔςΟΞϓϦʹ౉͢͜ͱͳ͘ɺ֎෦γεςϜ͕ ؅ཧ͢ΔΤϯυϢʔβʔͷϦιʔεʹର͢ΔݶఆతͳΞΫηεݖΛऔಘͰ͖·͢ɻ OAuth 2.0ͱ͸
14. – Resource Owner (ϦιʔεΦʔφʔ) – Ϧιʔεͷॴ༗ऀ 
 – Client (ΫϥΠΞϯτ) – ϦιʔεΦʔφʔͷ୅ΘΓʹอޢ͞ΕͨϦ ιʔε΁ͷΞΫηεΛཁٻ͢ΔΞϓϦέʔ γϣϯ 
 – Authorization server (ೝՄαʔόʔ) – ݖݶҠৡͷ஥հΛ͢ΔγεςϜ 
 – Resource server (Ϧιʔεαʔόʔ) – ϦιʔεΛ؅ཧ͢ΔγεςϜ OAuthͷొ৔ਓ෺ https://datatracker.ietf.org/doc/html/ rfc6749
15. Mauticʹ౰ͯ͸ΊΔͱɾɾ MauticͷϩάΠϯϢʔβʔ όοναʔόʔɺCLIɺαʔυύʔςΟΞ ϓϦͳͲ Mauticαʔόʔ – Resource Owner (ϦιʔεΦʔφʔ) – Ϧιʔεͷॴ༗ऀ 
 – Client (ΫϥΠΞϯτ) – ϦιʔεΦʔφʔͷ୅ΘΓʹอޢ͞ΕͨϦ ιʔε΁ͷΞΫηεΛཁٻ͢ΔΞϓϦέʔ γϣϯ 
 – Authorization server (ೝՄαʔόʔ) – ݖݶҠৡͷ஥հΛ͢ΔγεςϜ 
 – Resource server (Ϧιʔεαʔόʔ) – ϦιʔεΛ؅ཧ͢ΔγεςϜ
16. – Authorization code grant – ࠷΋҆શͰ࠷΋ෳࡶͳϑϩʔɻAuthorization codeΛհͯ͠ΞΫηετʔΫϯΛൃߦ͠·͢ɻ 
 – Client credentials grant – ϦιʔεΦʔφʔΛհ͞ͳ͍ϑϩʔɻcronδϣϒ࣮ߦͳͲϚγϯؒೝূ͕ߦ͑·͢ɻ 
 – Resource owner password credentials grant – (ඇਪ঑) ΫϥΠΞϯτ͕ϦιʔεαʔόʔͷϑΝʔετύʔςΟͰ͋Δ৔߹ʹ༗ޮͰ͢ɻ 
 – Implicit grant – (ඇਪ঑) JavaScript΍ϞόΠϧΞϓϦ޲͚ʹ༻ҙ͞Ε͍ͯͨϑϩʔͰ͢ɻ άϥϯτλΠϓͱ͸ ΫϥΠΞϯτ͸ΞΫηετʔΫϯΛ༻͍ͯϦιʔεαʔόʔʹΞΫηε͠·͢ɻRFCͰ࢓༷͕ެ։͞Ε͍ͯ ΔΞΫηετʔΫϯͷൃߦํ๏(=άϥϯτλΠϓ)Λ঺հ͠·͢ɻ
17. – Authorization code grant – ࠷΋҆શͰ࠷΋ෳࡶͳϑϩʔɻAuthorization codeΛհͯ͠ΞΫηετʔΫϯΛൃߦ͠·͢ɻ 
 – Client credentials grant – ϦιʔεΦʔφʔΛհ͞ͳ͍ϑϩʔɻcronδϣϒ࣮ߦͳͲϚγϯؒೝূ͕ߦ͑·͢ɻ 
 – Resource owner password credentials grant – (ඇਪ঑) ΫϥΠΞϯτ͕ϦιʔεαʔόʔͷϑΝʔετύʔςΟͰ͋Δ৔߹ʹ༗ޮͰ͢ɻ 
 – Implicit grant – (ඇਪ঑) JavaScript΍ϞόΠϧΞϓϦ޲͚ʹ༻ҙ͞Ε͍ͯͨϑϩʔͰ͢ɻ Mautic͕αϙʔτ͢ΔάϥϯτλΠϓ Mautic͕αϙʔτ͍ͯ͠ΔάϥϯτλΠϓ͸࣍ͷ2ͭͰ͢ɻ
18. τʔΫϯൃߦํ๏ͷҧ͍ Authorization code͔ΒΞΫηετʔΫϯͷҾ͖׵͑ʹ͸ΫϥΠΞϯ τIDͱΫϥΠΞϯτγʔΫϨοτ͕ඞཁͳͷͰɺAuthorization code ୯ಠͰྲྀग़ͯ͠΋ϦεΫΛ௿͘཈͑ΒΕ·͢ɻ༗ޮظݶͷ௕͍Ϧϑ ϨογϡτʔΫϯΛ͕ൃߦ͞ΕΔ͜ͱͰɺΞΫηετʔΫϯͷ༗ޮظ ݶ͕੾Εͨޙʹɺ࠶౓ϦιʔεΦʔφʔͷೝূΛߦΘͳͯ͘΋ΞΫη ετʔΫϯΛ࠶ൃߦ͢Δ͜ͱ͕ՄೳͰ͢Ň Client credentials grant ΫϥΠΞϯτͱಉҰͷϦιʔεΦʔφʔ͕อ༗͢ΔϦιʔεʹΞΫη εͨ͠ΓɺϦιʔεΦʔφʔ͔Βͷݖݶҕৡ͕ඞཁͳ͍ϦιʔεʹΞ Ϋηε͢Δ৔߹ʹ༗ޮͰ͢ɻϦιʔεΦʔφʔΛհ͞ͳ͍ͨΊɺcron δϣϒͷ࣮ߦ౳Λߦ͏ͨΊͷϚγϯؒೝূ͕ߦ͑·͢ɻ Authorization code grant
19. – MauticͰ༻ҙ͞Ε͍ͯΔೝՄΤϯυϙΠϯτɺτʔΫϯΤϯυϙΠϯτ͸࣍ͷ௨ΓͰ͢ɻ – ೝՄΤϯυϙΠϯτ – https://your-mautic.com/oauth/v2/authorize 
 – τʔΫϯΤϯυϙΠϯτ – https://your-mautic.com/oauth/v2/token ΤϯυϙΠϯτ
20. – [ωδϚʔΫ] > [APIΫϨσϯγϟϧ] ͔ΒɺOAuthͷͨΊͷAPIΩʔΛൃߦͰ͖·͢ɻ APIΩʔͷ؅ཧ - Ұཡը໘
21. ΫϥΠΞϯτID ΫϥΠΞϯτγʔΫ Ϩοτ APIΩʔͷ؅ཧ - Ұཡը໘
22. – [৽ن] Ϙλϯ͔ΒAPIΩʔΛൃߦͰ͖·͢ɻ APIΩʔͷ؅ཧ - ৽ن࡞੒
23. APIϦΫΤετΛςετ͢Δ
24. – Web APIͷ։ൃςετπʔϧͰ͋ΔPostmanΛ࢖͏ͱɺOAuthʹΑΔAPIϦΫΤετΛ؆୯ʹ ࢼ͢͜ͱ͕Ͱ͖·͢ɻ – ͜͜Ͱ͸ɺClient credentials grant Λར༻ͨ͠APIϦΫΤετͷํ๏Λ঺հ͠·͢ɻ PostmanͰAPIϦΫΤετ
25. 2. Authorizationλ ϒʹҠಈ 3. OAuth 2.0 Λબ୒ 1. ྫͱͯ͠GET Contacts ϦΫΤετͰࢼ͢
26. MauticͷτʔΫϯΤϯυϙΠϯτΛࢦఆ 
 https://your-mautic.com/oauth/v2/token ΫϥΠΞϯτIDΛࢦఆ ΫϥΠΞϯτγʔΫϨοτΛࢦఆ ະࢦఆ(Mautic͸είʔϓະରԠ) Send client credentials in body Λબ୒ ΫϦοΫ Client CredentialsΛબ୒
27. [Use Token] ΛΫϦοΫ͢Δͱ Access Token߲໨ʹࣗಈతʹ ೖྗ͞ΕΔ
28. ΞΫηετʔΫϯ͕खʹೖͬͨ ͷͰɺAPIϦΫΤετͷ४උ͕ ੔͍·ͨ͠ʂSendΛΫϦοΫ ԼͷλϒʹϨεϙϯεσʔλ͕ දࣔ͞Ε·͢
29. MauticͱKintoneΛ ࿈ܞ͢Δ
30. CRMπʔϧͱͷ࿈ܞ
31. CRMπʔϧͱͷ࿈ܞ MAπʔϧ CRM
32. – Mautic Conference Global 2021 ͷηογϣϯΛ͝ࢀর͍ͩ͘͞ɻ Salesforceͱͷ࿈ܞʹ͍ͭͯ͸ɾɾ https://www.youtube.com/watch?v=HZzKzZnTz5A
33. – MauticͷREST APIͱkintoneͷJavaScriptΧ ελϚΠζΛར༻ͯ͠ɺKintoneϨίʔυ ʹҰக͢ΔMauticίϯλΫτ৘ใΛදࣔ͢ Δ࿈ܞσϞͰ঺հ͠·͢ɻ Kintoneͱ࿈ܞͯ͠ΈΑ͏
34. – MauticͷREST APIʹ͍ͭͯ·ͱΊ·ͨ͠ɻ – MauticͷREST APIʹ͍ͭͯ – REST APIͷ࢖͍ํ – OAuthʹΑΔೝূೝՄ – APIϦΫΤετΛςετ͢Δ – MauticͱKintoneΛ࿈ܞ͢Δ ྑ͍APIϥΠϑΛʂ ·ͱΊ
35. THANK YOU