Google Ads API 徹底入門その2 Factories を使いこなす

Google Ads の情報を技術ブログに連載していきたい id:hano_tea です。こんにちは。 Google Ads API が β 版に戻るという大事件がありましたが、気にせず解説記事を書いていきます。

さて、今回は「Google Ads API 徹底入門」に続く Google Ads API 記事第2弾、「Factories を使いこなす」です。前回の記事はこちら。

developer.feedforce.jp

Google Ads API と言いつつ、内容的には Ruby クライアントに限定された話なので、別の言語で Ads API を使っている方には参考にならないかと思いますが、何卒ご了承ください。

Factories とは

Google Ads API Client Library for Ruby の 2.1.0 で Factories という機能が追加されました。

developers.google.com

例えば CampaignBudget リソースを作成するためのコードは、 Factories を使わないと以下のようになります。

cbudget = client.resource(:CampaignBudget)
cbudget.name = client.wrapper.string(sprintf('Interplanetary Budget %s',(Time.new.to_f * 1000).to_i))
cbudget.delivery_method = client.enum(:BudgetDeliveryMethod)::STANDARD
cbudget.amount_micros = client.wrapper.int64(1000 * 1_000_000)

cbudget_operation = client.operation(:CampaignBudget)
cbudget_operation['create'] = cbudget

cbudget_service = client.service(:CampaignBudget)
cbudget_service.mutate(customer_uid, [cbudget_operation])

上記のように、 resource, operation, service を個別に作成する必要があります。また、リソースの作成であれば

operation['create'] に対して作成対象のリソースを入れる
更にそれを service に渡してリクエストを行う

という手順が必要でした。

上記の CampaignBudget の作成は、新たに導入された Factories を使うと以下のように書けます。

cbudget_operation = client.operation.create_resource.campaign_budget do |cb|
  cb.name = client.wrapper.string(sprintf('Interplanetary Budget %s',(Time.new.to_f * 1000).to_i))
  cb.delivery_method = client.enum(:BudgetDeliveryMethod)::STANDARD
  cb.amount_micros = client.wrapper.int64(1000 * 1_000_000)
end

client.service.campaign_budget.mutate_campaign_budgets(client_uid, [cbudget_operation])

いかがでしょうか。だいぶスッキリ書けるようになっているのが分かるかと思います。

リソースの作成を行いたいときは client.operation.create_{resource_type}.{resource_type} { |instance_of_resource| } のように記述すると、いちいちそれぞれの resource を個別に作成したり、 operation['create'] に resource インスタンスを詰め込むといった手順を踏まずに済ませることができます。

※ {resource_type} は各リソースの種別名（Campaign とか）を入れてください。

また、 service についても、 client.service.{resource_type}.mutate_{resource_types} のように記述すると service インスタンスを一回作成する手間を省くことができます。

Factories が使える操作

Factories は以下の3種類のオブジェクトを扱う時に使うことができます。

Operations
Resources
Services

Operations

Operations はこれまで client.operation(:ResourceType) のような操作で作成していましたが、 Factories を使うと以下のように記述することができるようになります。

operation = client.operation.{operation_type}_resouce.{resource_type} do |instance_of_resource|
  # instance_of_resource の各アトリビュートを設定する
  # ex. instance_of_resource.name = 'hogehoge'
end

{operation_type} には行いたい操作、 create, update, remove のいずれかが入ります。また、 {resource_type} には操作対象のリソース種別名が入ります。実際の例は Factories とは で記述しているので割愛します。ブロック引数で操作対象のリソースのインスタンス（上記の例の instance_of_resource）が受け取れるので、ブロック内ではそのインスタンスのアトリビュートを設定するための操作を記述します。

Factories の効果が一番大きいのはこの Operations の作成かもしれないです。 Operations の作成と言いつつ、実際には

client.resource(:ResourceType) によるリソースの作成、及びその後のアトリビュート設定
client.operation(:ResourceType) による Operation の作成
operation['{operation_type}'] = resource による操作種別および操作対象の設定

という3つの操作を同時に行うことができるイメージです。

Resources

Resources はこれまで client.resource(:ResourceType) のような操作で作成していましたが、 Factories を使うと以下のように記述することができるようになります。

resource = client.resource.{resource_type} do |instance_of_resource|
  # instance_of_resource の各アトリビュートを設定する
  # ex. instance_of_resource.name = 'hogehoge'
end

ブロック周りの使い方は Operations の Factories と同様です。以前の書き方に比べてそこまで大きく変わるわけではないですが、ブロックを使ってインスタンスの生成とアトリビュートの設定が同時にできるのでこれも便利ですね。

Services

Services はこれまで client.service(:ResourceType) のような操作で作成していましたが、 Factories を使うと以下のように記述することができるようになります。

service = client.service.{service_type}

これはあんまり以前までと変わらない（書き方が変わったぐらい）のであんまりありがたみは無いかもしれない…？実際に使うときは以下のように Operations の作成と組み合わせて使うことが多いかと思います。

cbudget_operation = client.operation.create_resource.campaign_budget do |cb|
  cb.name = ...
end

client.service.campaign_budget.mutate_campaign_budgets(client_uid, [cbudget_operation])

なお、これまでの記法でもメソッドチェインさせて同じように書くこともできたので、本当に書き方が変わっただけです。