Mautic API LibraryでMautic APIをコールする(oAuth2認証編)

MauticのデータをMautic外で扱いたい時、Mauticが持つREST APIをコールすることができます。そしてREST APIの呼び出し方法については、公式のドキュメントに「PHPのライブラリがあるからそれを使ってください」と書かれています。

ということで何回かに分けて、「Mautic API Library」を使ってMauticのREST APIを利用する方法をご紹介します。

ライブラリのインストール

まずはライブラリをインストールします。
composerを使って手に入れることが可能ですので、作業ディレクトリに移動してから以下のコマンドでインストールします。

$ cd /PATH/TO/WORKSPACE
$ composer require mautic/api-library

実行すると、以下のようにcomposerによるインストールが始まります。

Using version ^2.1 for mautic/api-library
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing psr/log (1.0.2)
    Downloading: 100%

  - Installing mautic/api-library (2.1.1)
    Downloading: 100%

Writing lock file
Generating autoload files

MauticでAPIクレデンシャルを作成する

%e3%82%b9%e3%82%af%e3%83%aa%e3%83%bc%e3%83%b3%e3%82%b7%e3%83%a7%e3%83%83%e3%83%88-2016-10-26-19-00-25

作成すると、Client KeyとClient Secret Keyが生成されますので、控えておきましょう。

oAuth2認証を実施する

それでは早速APIへの認証を始めます。

サンプルコード:開発ドキュメントのコードを参考に、以下のようなファイルを作成します。($settingsの値は自分の値に変更してください。)

index.php

<?php
// Bootup the Composer autoloader
include __DIR__ . '/vendor/autoload.php';
use Mautic\Auth\ApiAuth;

// ApiAuth::initiate will accept an array of OAuth settings
$settings = array(
    'baseUrl'      => 'https://YOUR_MAUTIC_URL',
    'version'      => 'OAuth2',
    'clientKey'    => 'YOUR_MAUTIC_CLIENT_KEY',
    'clientSecret' => 'YOUR_MAUTIC_CLIENT_SECRET',
    'callback'     => 'http://YOUR_WEBSITE_URL'
);
session_start();
// Initiate the auth object
$auth = ApiAuth::initiate($settings);

if ($auth->validateAccessToken()) {
    if ($auth->accessTokenUpdated()) {
        $accessTokenData = $auth->getAccessTokenData();
        foreach($accessTokenData as $key => $value ) {
            echo "$key: $value<br/>";
        }
    }
}

index.phpを実行する

あとは先程作成したファイルを実行すればOKです。

ブラウザからアクセスすると、Mauticの認証画面へリダイレクトされます。

%e3%82%b9%e3%82%af%e3%83%aa%e3%83%bc%e3%83%b3%e3%82%b7%e3%83%a7%e3%83%83%e3%83%88-2016-10-26-19-04-22

許可をクリックすると、上で作成したコードの$accessTokenDataにアクセストークンなどのデータを含めた状態でコールバックURLにアクセスします。
%e3%82%b9%e3%82%af%e3%83%aa%e3%83%bc%e3%83%b3%e3%82%b7%e3%83%a7%e3%83%83%e3%83%88-2016-10-26-19-02-15

今回はここまで。
次回からはこのアクセストークンの情報を使って実際にデータの取得などを行ってみます。

Mautic REST APIを有効化する

MauticのデータをMautic外で扱いたい時、Mauticが持つREST APIをコールすることができます。
このMautic REST APIはデフォルトでは無効化されていますので、管理画面から有効化しましょう。

管理画面にアクセス

mautic
管理画面にログインした後、画面右上にある歯車ボタンをクリックします。

このボタンをクリックすると、Mauticの設定に関するパネルが開きますので、

開かれたパネルの中から「Configuration」をクリックしましょう。

mautic

API Settingsへ移動し、有効化する

「Configuration」ではAPIだけでなく、管理画面の言語設定やメールに関する設定なども行うことができます。

画面左側にサブメニューが表示されていますので、この中から「API Settings」をクリックしましょう。

%e3%82%b9%e3%82%af%e3%83%aa%e3%83%bc%e3%83%b3%e3%82%b7%e3%83%a7%e3%83%83%e3%83%88-2016-10-26-18-31-35

「API enabled?」という項目がありますので、ここをYESに切り替えれて保存すればOKです。

設定が完了している場合は、以下の画像のように右側のメニューに「API Credentials」という項目が追加されています。

mautic

ドキュメントなど

これでMautic REST APIの利用準備ができました。

Mautic REST APIの利用方法等については、公式の開発ドキュメントをご確認ください。

https://developer.mautic.org/#rest-api

このブログでも随時使い方について紹介してまいります。

Mautic1.4.1をぶっ飛ばしたときの復旧メモ

思いっきりやらかしたので、反省を込めて覚書。いわゆるところの始末書的な意味もこめて。

やらかしたこと

せっかくAWS使ってるのに、スナップショットを取らずにMauticをアップデートを実行した。
その結果アップデートに失敗してMauticにログインできなくなった。

根本的な問題

アップデートの様な大きな変更を入れる時は必ずスナップショットを作成する。

復旧までの覚書

やらかした先人はすでにいたので参考にする。
Uh Oh, Mautic upgrade was not successful

ファイルの退避

ソースコードを新しくとってくるので、既存のファイルを一時的に移動させる。

$ sudo mkdir /tmp/html.bk
$ sudo mv /var/www/html/* /tmp/html.bk/

Mauticコアの再取得

Mauticのコアファイルを新しくとってきます。
調子に乗ってここで最新バージョンをとってくるのではなく、おとなしくアップデート前のものをとってきましょう。復旧させるのが第一です。

$ sudo su -
# cd /var/www/html
# wget https://github.com/mautic/mautic/archive/1.4.1.zip
# unzip 1.4.1.zip
# mv mautic-1.4.1/* ./
# rm -f 1.4.1.zip
# rm -rf mautic-1.4.1

設定ファイル及び各種ファイルの復旧

もとのMauticの情報やファイルを利用できるように各ファイルを移動させます。
万が一に備えてmvではなくcpを使用します。

# cp /tmp/html.bk/app/config/local.php /var/www/html/app/config
# \cp -Rf /tmp/html.bk/media/* /var/www/html/media/
# \cp -Rf /tmp/html.bk/themes/* /var/www/html/themes/
# \cp -Rf /tmp/html.bk/plugins/* /var/www/html/plugins/

composer install

Mauticで利用するライブラリはComposerで管理されていますので、インストールします。

# cd /var/www/html
# composer install

パーミッションの復旧

ここまでrootで作業してるので、権限をapacheに戻しましょう。

# chown -R apache:apache /var/www/html
# chmod -R 775 /var/www/html/app/cache
# chmod -R 775 /var/www/html/app/logs
# chmod -R 775 /var/www/html/app/config
# exit

表示確認

ここまでやればサイトの表示は復旧している(はず)です。
今度はちゃんとスナップショットなどのバックアップを作成した上でアップデートを実施しましょう。

最後に

この記事を最後まで読む必要があった人は、とりあえず今すぐスナップショット作っておきましょう。
そうすれば少なくとも復旧したこのタイミングまでは簡単にロールバックができるようになります。

Mautic1.4.1から2.x系にアップデートする

Mauticを触っていると、以下の様なコマンドがあったり、管理画面で「Mauticアップデートしませんか?」という案内と共にアップデートボタンが表示されたりと、WordPressなどに近い感じで気軽にアップデートできるようになってます。

$ php app/console help mautic:update:apply

ただ、1.x系から2.x系へのアップデートに関してはどちらも絶対に使っちゃダメです。

リリースノートにもバッチシ「使うな」って書かれてます。

Our CLI command, php app/console mautic:update:apply WILL NOT WORK
https://github.com/mautic/mautic/releases/tag/2.0.0

これを知らずにアップデートを実行してしまうと、非常につらい思いをします。万が一やっちゃったという人は、Mautic1.4.1をぶっ飛ばしたときの復旧メモを参考に一旦復旧させましょう。というかアップデートはマジでバックアップとってからやりましょう

1.x系から2.x系へのアップデート方法

じゃあどうやってアップデートすれば良いのかですが、上記のリリースノートを読むと「このファイルを実行してくれ」という案内があります。

We have provided an upgrade script to use instead. Please download this script from https://raw.githubusercontent.com/mautic/mautic/master/upgrade.php, place in the root of your Mautic installation, and run it from CLI with php upgrade.php. It will fetch 2.0.0 and proceed to upgrade your Mautic installation.

https://github.com/mautic/mautic/releases/tag/2.0.0

こいつを使ってアップグレードしましょう。

実行した環境

今回は、Mautic Powered by AMIAGEで作られたMauticを使用しています。

実行ユーザーなどが異なる可能性がありますので、他の環境で実行される際はご注意ください。

実行コード

$ cd /var/www/html
$ sudo mv upgrade.php /tmp
$ sudo wget https://raw.githubusercontent.com/mautic/mautic/master/upgrade.php
$ sudo php upgrade.php
$ sudo chown -R apache:apache ./
$ sudo rm 2.1.1-update.zip

第2回 Mautic勉強会@TAM コワーキング大阪にて、Mauticの使い方を紹介するセッションを行いました

関西はMautic Meeupがまだ開催されていない地域ですが、TAMさんによる勉強会は定期的に開催されています。

その中で「とりあえず貰った名刺を Mauticにいれるところからはじめよう」というセッションをさせて頂きました。

当日のスライド

「触ってみないとわからないこともあるよ」という話

当日会場に20名近くの方が来て頂いてましたが、「Mauticを実際に触ったことがある」という方は2〜3人程度でした。

確かにMAツールとして注目されはじめたばかりだということや、マーケティングプランがないと実運用には使いづらいという問題があるとは思います。

ただ流石にちょっと少なすぎるような気もして、個人的にはもうちょっと「よくわからんけど、とりあえず使ってみたー!!」みたいな人も出てきてくれないかなという印象です。

Mautic Meetup Tokyo #3であった「Mauticインストールしてみた というセッションとかまさにそうですね。

ちゃんと使うにはMauticを触る前にやるべきことが多いのは確かです。ただ、「Mauticで何ができて、何ができないのか」ということは触ってみないとわかりません。

幸いにもMautic Cloud Freeという無料でMauticを触れるSaaSがリリースされています。

今回のセッションで紹介したような、「とりあえず名刺もらった人にメール送信するだけ」とかの使い方で大丈夫です。

とりあえず「Mauticがどういうものか」を触って覚えてみて、まだ触っていない人に自分の気付きを共有するということができる人がもっと増えると良いなと思います。