README

此项目托管了Google Ads API的PHP客户端库。

功能

• 通过Composer和Packagist分发。
• 轻松管理凭证。
• 轻松创建Google Ads API服务客户端。

要求

• 此库依赖于Composer。如果您尚未在计算机上安装它，请遵循Linux/Unix/OS X安装指南或Windows安装指南。在本指南的其余部分，我们假设您正在使用Linux/Unix/OS X并且已全局安装Composer，因此，您的安装Composer可以通过命令行作为composer使用。
• 系统要求和依赖关系可以在本库的composer.json中找到。
  • 此库所需的最小PHP版本是PHP开发团队仍然提供安全修复的最低PHP版本。每当此类版本被淘汰时，我们将相应地更新composer文件。目前，更新频率大约每年一次，基于官方计划。
  • 要安装gRPC PHP扩展，请遵循此页的“安装gRPC PHP扩展”部分。
    1. 使用命令sudo pecl install grpc安装扩展。
    2. 将一行extension=grpc.so添加到php.ini文件中。
    3. 在终端中运行php -i | grep grpc：如果返回一些内容，则表示安装和配置良好。
  • 要安装Protobuf PHP扩展，请遵循此页下“Protobuf Runtime库”下的“C实现”部分。如果您遇到任何错误，可以跳过此步骤，而是使用PHP实现。更多详细信息请参阅Protobuf部分。
    1. 使用命令sudo pecl install protobuf安装扩展。
    2. 将一行extension=protobuf.so添加到php.ini文件中。
    3. 在终端中运行php -i | grep protobuf：如果返回一些内容，则表示安装和配置良好。
• 您需要一个开发者令牌才能连接到Google Ads API。

入门

1. 通过

   git clone https://github.com/googleads/google-ads-php.git
   

2. 切换到google-ads-php目录。

   cd google-ads-php
   

   您将看到一些文件和子目录

   • composer.json：Composer文件，其中包含此库的要求。
   • src：库的源代码。
   • tests：库代码的测试。
   • examples：许多示例，演示如何通过Google Ads API使用库来执行常见用例。
   • metadata：一些由源代码内部使用的元数据文件。它们是自动生成的文件，因此您不应修改它们。

3. 在命令提示符下运行 composer install。这将安装使用库和运行示例所需的所有依赖项。

4. 设置您的 OAuth2 凭据。

   Google Ads API 使用 OAuth2 作为认证机制。根据您的用例选择下面的适当选项，并阅读并遵循示例打印到控制台上的说明。

   如果您已经有了 AdWords API 的凭据...

   • 如果您有用于 AdWords API 的 adsapi_php.ini 文件，将其复制并命名为 google_ads_php.ini。只需将节名称从 [ADWORDS] 更改为 [GOOGLE_ADS]。

   • 如果没有文件，将示例 google_ads_php.ini 复制到您的 主目录。此库通过使用 EnvironmentalVariables::getHome() 来确定您的计算机的主目录。

   如果您使用自己的凭据访问 Google Ads API...

   • 将示例 google_ads_php.ini 复制到您的 主目录。此库通过使用 EnvironmentalVariables::getHome() 来确定您的计算机的主目录。

   • 按照 https://developers.google.com/google-ads/api/docs/oauth/cloud-project 中的说明创建 OAuth2 客户端 ID 和密钥，用于 已安装的应用程序 OAuth2 流。

   • 运行 AuthenticateInStandaloneApplication 示例，该示例将提示您输入 OAuth2 客户端 ID 和密钥。

   • 将示例的最后一步的输出复制到您主目录中的 google_ads_php.ini 文件中。别忘了填写您的开发人员令牌。

5. 运行 GetCampaigns 示例 以测试您的凭据是否有效。您还需要作为命令行参数传递您的 Google Ads 账户的客户 ID（不带破折号）

   php examples/BasicOperations/GetCampaigns.php --customerId <YOUR_CUSTOMER_ID>
   

   注意：代码示例旨在从命令提示符运行，而不是通过网页浏览器。

6. 探索其他示例。

   示例目录 examples 包含几个有用的示例。大多数示例都需要参数。您可以通过将 --help 作为命令行参数运行代码示例来查看所需的参数。

基本用法

要通过 Google Ads API 发送请求，您首先需要创建一个 GoogleAdsClient。为了方便起见，您可以将所需的设置存储在具有以下格式的属性文件（google_ads_php.ini）中

[GOOGLE_ADS]
developerToken = "INSERT_DEVELOPER_TOKEN_HERE"

[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

如果您以管理帐户的身份进行认证，您还必须指定（不带破折号）的管理帐户 ID 作为登录客户 ID

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

此配置文件格式类似于 AdWords API 的 PHP 客户端库 使用的格式。

如果您在主目录中有一个上述格式的 google_ads_php.ini 配置文件，您可以使用以下方式使用无参数版本的 fromFile()

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

其中 $oAuth2Credential 是通过以下方式创建的

$oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();

如果您的配置文件不在您的主目录中，您可以将文件位置传递给 fromFile 方法，如下所示

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();
$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

您还可以通过指定运行时客户端 ID、客户端密钥和刷新令牌来构造 OAuth2 凭据对象，然后将该对象传递给 GoogleAdsClientBuilder，如下所示

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID')
    ->withClientSecret('INSERT_CLIENT_SECRET')
    ->withRefreshToken('INSERT_REFRESH_TOKEN')
    ->build();
$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withDeveloperToken('INSERT_DEVELOPER_TOKEN_HERE')
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

获取服务客户端

一旦你有了 GoogleAdsClient 的实例，你可以使用 get...ServiceClient() 中的任一方法获取特定服务的服务客户端。

传输

可以使用不同类型的传输。有关更多信息，请参阅传输指南。

Protobuf

Protobuf 在请求 Google Ads API 时，无论使用哪种传输都会使用。

有关更多信息，请参阅Protobuf 指南。

在 Docker 容器中运行

请参阅在 Docker 容器中运行指南。

日志记录

请参阅日志记录指南。

代理配置

请参阅代理指南。

性能

请参阅性能指南。

杂项

Wiki

• https://github.com/googleads/google-ads-php/wiki

问题跟踪器

• https://github.com/googleads/google-ads-php/issues

API 文档

• https://developers.google.com/google-ads/api/docs

支持论坛

• https://groups.google.com/forum/#!forum/adwords-api

作者

• Thanet Knack Praneenararat
• Mattia Tommasone
• Pierrick Voulet