Cmdlets for Google Ads

Build 22.0.8479

接続の確立

CData Cmdlets ユーザーは、データモジュールをインストールし、接続プロパティを設定してスクリプトを開始できます。このセクションでは、CSV インポートおよびエクスポートcmdlet などのネイティブPowerShell cmdlet でGoogleAds Cmdlets を使用する例を示します。

インストールおよび接続

PSGet がある場合は、PowerShell Gallery から次のコマンドを使ってcmdlet をインストールできます。CData サイトからセットアップを取得することもできます。 

Install-Module GoogleAdsCmdlets

プロファイルに以下を追加すると、次のセッションでcmdlet がロードされます。 

Import-Module GoogleAdsCmdlets;

Connect-GAds cmdlet を使って、別のcmdlet に渡すことができる接続オブジェクトを作成します。 

$conn = Connect-GAds -ClientCustomerId "MyClientCustomerId" -DeveloperToken "MyDevToken"

Google Ads への接続

認証プロパティを追加する前に、次の接続プロパティを設定してください。

  • DeveloperToken：AdWords アカウントの開発者トークンに設定。AdWords API にサインアップすることで、開発者トークンを取得できます。これには、MCC アカウントでAdWords サイトにログインし、［設定］->［アカウント設定］->［AdWords API Center］に進みます。API アクセスを適用すると、Google から追加の手順に関するE メールが届きます。ペンディングステータスのトークンを受け取ります。トークンはテスト用であり、ライブデータへの接続は許可されていません。Google から質問票への記入依頼が届きますので、これをGoogle が受け取り、承認した時点でアクティブな開発者トークンを受領できます。
  • ClientCustomerId：Google Ads お客様ID に設定。ClientCustomerId は、Google Ads UI の右上隅にある人物のアイコンをクリック後、ヘルプメニューの下部で確認できます。

    Note：この接続プロパティは、'AdWords' Schema を使用している場合にのみ必須です。

NOTE：以下のセクションは、これらの接続プロパティがすでに設定済みであることを前提として書かれています。

複数のアカウントからデータを取得

ドライバーの一般的な使用方法は、複数のお客様ID からデータを取得することです。これは、多数のアカウント / ClientCustomerId を含むGoogle Ads MCC アカウントを持っている場合に有効です。例えば、以下のようにWHERE 句にCustomerId を指定することで、必要なアカウントのデータをクエリして取得することができます。 
SELECT * FROM AdGroupAd WHERE CustomerId='3333333333'
SELECT * FROM AdGroupAd WHERE CustomerId IN ('1111111111', '2222222222')
WHERE 句でCustomerId を指定すると、ドライバーはClientCustomerId 接続プロパティを無視します。

Google Ads への認証

Google Ads へのすべての接続はOAuth を使用して認証されます。本製品 は、認証にユーザーアカウント、サービスアカウントおよびGCP インスタンスアカウントの使用をサポートします。

ユーザーアカウント（OAuth）

すべてのユーザーアカウントフローで、AuthScheme をOAuth に設定する必要があります。 CData は、OAuth デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。代わりに、カスタムOAuth アプリケーションを作成することも可能です。カスタムアプリケーションの作成およびその理由については、カスタムOAuth アプリの作成 を参照してください。

認証に関する2つの方法の違いは、カスタムOAuth アプリケーションを使用する場合に、2つの接続プロパティを追加で設定する必要があることだけです。

次の接続プロパティを設定して、接続してください。

  • OAuthClientId：（カスタムアプリのみ）カスタムOAuth アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：（カスタムアプリのみ）カスタムOAuth アプリケーション設定のクライアントシークレットに設定。
接続すると、本製品 はデフォルトブラウザでOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。以下のように本製品 がOAuth プロセスを完了します。

  • コールバックURL からアクセストークンを取得します。
  • 古いトークンの期限が切れたときは、新しいアクセストークンを取得します。
  • OAuthSettingsLocation にOAuth 値を保存し、接続間で永続化します。

ヘッドレスマシン

ヘッドレスマシンのユーザーアカウントでOAuth を使用するようにドライバーを設定するには、インターネットブラウザに対応した別の端末で認証する必要があります。

  1. 以下のオプションから選択します。
    • オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
    • オプション2：インターネットブラウザに対応したマシンに本製品 をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。
  2. 次に、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品 を設定します。

オプション1：Verifier code を取得および交換

Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。

インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得する方法は次のとおりです。

  1. 以下のオプションから選択します。
    • 埋め込みOAuth アプリケーションを使用する場合は、Google Ads OAuth endpoint をクリックし、ブラウザでエンドポイントを開きます。
    • カスタムOAuth アプリケーションを使用するには、以下のプロパティを設定し、認証URL を作成します。
      • InitiateOAuth：OFF に設定。
      • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
      • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
      次に、適切なCallbackURL を指定してGetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。
  2. ログインして、本製品 にアクセス許可を与えます。すると、verifier code を含むコールバックURL にリダイレクトされます。
  3. verifier code の値を保存します。後ほどこれをOAuthVerifier 接続プロパティに設定します。
次に、OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換する必要があります。次のプロパティを設定します。

ヘッドレスマシンでは、次の接続プロパティを設定してOAuth 認証値を取得します。

  • InitiateOAuth：REFRESH に設定。
  • OAuthVerifier：verifier code に設定。
  • OAuthClientId：（カスタムアプリのみ）カスタムOAuth アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：（カスタムアプリのみ）カスタムOAuth アプリケーション設定のクライアントシークレットに設定。
  • OAuthSettingsLocation：これを設定すると、暗号化されたOAuth 認証値が指定されたファイルに永続化されます。

OAuth 設定ファイルが生成されたら、以下のように接続プロパティをリセットする必要があります。

  • InitiateOAuth：REFRESH に設定。
  • OAuthClientId：（カスタムアプリのみ）アプリケーションの登録時に割り当てられたクライアントId に設定。
  • OAuthClientSecret：（カスタムアプリのみ）アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
  • OAuthSettingsLocation：暗号化されたOAuth 認証値を含むファイルに設定。アクセストークンの自動リフレッシュを有効にするために、このファイルが本製品 に読み書きのアクセス許可を与えることを確認してください。

オプション2：OAuth 設定を転送

ヘッドレスマシンでの接続に先立ち、インターネットブラウザに対応したデバイスでドライバとの接続を作成し、インストールする必要があります。上述の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。

「デスクトップアプリケーション」の手順が完了すると、生成された認証値は、OAuthSettingsLocation で指定されたパスに暗号化されて書き込まれます。デフォルトのファイル名はOAuthSettings.txt です。

接続が正常にテストされたら、OAuth 設定ファイルをヘッドレスマシンにコピーします。

ヘッドレスマシンで、次の接続プロパティを設定し、データに接続します。

  • InitiateOAuth：REFRESH に設定。
  • OAuthClientId：（カスタムアプリのみ）アプリケーションの登録時に割り当てられたクライアントId に設定。
  • OAuthClientSecret：（カスタムアプリのみ）アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
  • OAuthSettingsLocation：OAuth 設定ファイルのパスに設定。アクセストークンの自動リフレッシュを有効にするために、このファイルが本製品 に読み書きのアクセス許可を与えることを確認してください。

サービスアカウント（OAuthJWT）

サービスアカウントを使用して認証するには、新しいサービスアカウントを作成し、アカウント証明書のコピーを用意する必要があります。

JSON ファイルの場合は、以下のプロパティを設定します。

  • AuthScheme：OAuthJWT に設定。
  • OAuthJWTCertType：GOOGLEJSON に設定。
  • OAuthJWTCert：Google が提供する.json ファイルへのパスに設定。
  • OAuthJWTSubject：サービスアカウントはGSuite ドメインの一部であり、委任が有効である必要があります。このプロパティの値は、データにアクセスしたいユーザーのE メールアドレスでなければなりません。

PFX ファイルの場合は、以下のプロパティを設定する必要があります。

  • AuthScheme：サービスアカウントのE メールアドレスに設定。このアドレスには、通常iam.gserviceaccount.com ドメインが含まれます。
  • OAuthJWTSubject：サービスアカウントはGSuite ドメインの一部であり、委任が有効である必要があります。このプロパティの値は、データにアクセスしたいユーザーのE メールアドレスです。

サービスアカウントを持っていない場合は、カスタムOAuth アプリの作成 の手順に従って作成できます。

GCP インスタンスアカウント

GCP 仮想マシン上で実行している場合は、本製品 は仮想マシンに関連付けられたサービスアカウントを使用して認証できます。 このモードを使用するには、AuthScheme をGCPInstanceAccount に設定します。

データの取得

Select-GAds cmdlet はデータを取得するためのネイティブなPowerShell インターフェースを提供します。 

$results = Select-GAds -Connection $conn -Table "CampaignPerformance" -Columns @("Clicks, Device") -Where "Device='Mobile devices with full browsers'"
Invoke-GAds cmdlet はSQL インターフェースを提供します。このcmdlet を使うと、Query パラメータを介してSQL クエリを実行できます。

cmdlet 出力のパイプ処理

cmdlet は行オブジェクトをパイプラインに一度に一行ずつ返します。以下は、結果をCSV ファイルにエクスポートします。 

Select-GAds -Connection $conn -Table CampaignPerformance -Where "Device = 'Mobile devices with full browsers'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myCampaignPerformanceData.csv -NoTypeInformation

Select-GAds からの結果をSelect-Object cmdlet にパイプして、Export-CSV cmdlet にパイプする前にいくつかのプロパティを実行していることがわかるでしょう。これをする理由は、CData Cmdlets は接続、テーブル、およびカラムの情報を結果セットの各行オブジェクトに追加しますが、必ずしもその情報がCSV ファイルに必要ではないからです。

ただし、これによってcmdlet の出力を別のcmdlet にパイプすることが容易になります。以下に、結果セットをJSON に変換する例を示します。 

 
PS C:\> $conn  = Connect-GAds -ClientCustomerId "MyClientCustomerId" -DeveloperToken "MyDevToken" 
PS C:\> $row = Select-GAds -Connection $conn -Table "CampaignPerformance" -Columns (Clicks, Device) -Where "Device = 'Mobile devices with full browsers'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "CampaignPerformance",
  "Columns":  [

  ],
  "Clicks":  "MyClicks",
  "Device":  "MyDevice"
}

Copyright (c) 2023 CData Software, Inc. - All rights reserved.
Build 22.0.8479