googleads/googleads-php-libが新しくなりました

PHPからAdWordsのAPIを呼び出すとき、公式に提供されているクライアントライブラリである googleads/googleads-php-lib を使うことが多いと思います。（自前で頑張る場合は別） googleads/googleads-php-libは2016年12月に新バージョンが公開されて、従来とは利用方法が大きく変わりました。 個人的には特別な設定無しでcomposer requireできるようになったり、各APIバージョン別のnamespaceがついたことでPhpStormなどのIDEでコードが追いやすくなるなど、嬉しいことがいっぱいの更新でした！

従来のバージョンのgoogleads/googleads-php-libは 2017年7月末日でサポートが終了 しました。（従来版の最終バージョンは2017年6月にリリースされた v19.0.0 ） 旧バージョンからも利用できるAPIバージョンはv201705が最終となり、2017年8月にリリースされたAdWords API v201708以降は新バージョンからのみ利用できるようになっています。 今後もAdWords APIを使っていくのであれば、従来のバージョンを使っていた方も、そろそろ移行を考えなくてはいけません。

と言っても、長らく従来のバージョンを使っていた開発者から見ると、あまりに大きく変わりすぎてコードの書き直しが多数発生するため、更新に踏み切るには勇気が要るものです。 そこで、googleads/googleads-php-lib移行時に気をつけること（私が引っかかったポイント）をいくつか公開したいと思います。これから移行する開発者の皆様の、転ばぬ先の杖になれば幸いです。

アップグレード時に気をつけること

Predicateのパラメータは配列

たとえ演算子がEQUALSで、パラメータとして単独の値しか渡さない場合であってもパラメータ部分（第三引数）は必ず配列にする必要があります。 紛らわしいですが、WSDLから自動でPHPコードを生成しているので変更不可とのことです。（ https://github.com/googleads/googleads-php-lib/issues/227 ）

誤り

<?php
$predicate = new Predicate('hoge', 'EQUALS', 'foo')

正しい

<?php
$predicate = new Predicate('hoge', 'EQUALS', ['foo'])

トークンの手動リフレッシュは不要

今後はgoogleads/googleads-php-libの外ではrefresh_tokenのみを管理すれば良いことになります。

旧

<?php

// tokenは配列形式を保存しておく必要あり
$token = [
  'access_token' => 'xxx',
  'refresh_token' => 'yyy',
  'expires' => 123456789, // timestamp
  'clientId' => 'aaaa',
  'clientSecret' => 'bbbb',
];
// リフレッシュが必要かどうか確認
$handler = $adWordsUser->GetOAuth2Handler();
if ($handler->CanRefreshAccessToken($token) && $handler->ShouldRefreshAccessToken($token)) {
    // リフレッシュ
    $token = $handler->RefreshAccessToken($token);
}

新

<?php

// tokenはリフレッシュトークン文字列だけ保存しておけば良い
$refreshToken = 'yyy';
// リフレッシュトークンを渡すだけで良い。リフレッシュが必要な場合は自動でリフレッシュ。
$credential = (new OAuth2TokenBuilder())
    ->withClientId($clientId)
    ->withClientSecret($clientSecret)
    ->withRefreshToken($refreshToken)
    ->build()
;
$adWordsSession = (new AdWordsSessionBuilder())
    ->withDeveloperToken($developerToken)
    ->withOAuth2Credential($credential)
    ->build();

XXXOperationのコンストラクタ引数の順序変更

コンポーネントの操作を行うOperationクラス群（たとえば、CampaignOperation, AdGroupAdOperation等）のコンストラクタ引数の順番が、従来とは変更されています。

旧（たとえば v19.0.0のCampaignOperation ）

<?php

class XXXOperation
{
    public function __construct($operand, $operationType = null, $operator = null)
    {
        // ...
    }
}

新（たとえば v29.0.0のCampaignOperation ）

<?php

class XXXOperation
{
    public function __construct($operator = null, $operationType = null, $operand = null)
    {
        // ...
    }
}

• $operator が SET, REMOVE 等
• $operationType は基本的にnull指定で可
• $operand が実際に操作するオブジェクト（たとえば、Campaign, AdGroupAd 等）

実際に使わない値である$operationTypeのほうが$operandより先に来るのはしっくり来ませんが、やはりWSDLから自動で生成されているために変更不可のようです。

まとめ

新バージョンでは、多少引っかかっても前述したようにIDEでgoogleads-php-lib内のコードを追いやすくなったので、丁寧にコードを読んでいけば解決しやすくなっていると思います。 移行を終えてしまうと間違いなく良い方向に進化したと確信できるので、ためらっている方もAdWords API v201705が終了する（と予想される） 2018年5月 までに思い切って移行することをおすすめします。