README

此仓库托管了 Google Ad Manager SOAP API 的 PHP 客户端库。

AdWords API 已于 弃用。您可以使用新的客户端库 google-ads-php 来访问新的 Google Ads API。

重要 根据在 #777 中宣布的消息，此客户端库已更新，需要 PHP 8.0 作为最低版本。这意味着支持 PHP 7 的库的最终版本是 v61.0.0，支持 Google Ad Manager API v202208、v202211、v202302 和 v202305。

Google Ad Manager API v202305 预计将于 2024 年 5 月 弃用。因此，PHP 7 用户有大约一年的时间迁移到 PHP 8.0 或更高版本，以避免中断。

要求和准备

• 系统要求和依赖项可在该库的 composer.json 中找到。有关更多详细信息，请参阅此页面。
• 从版本 62.0.0 开始，此库需要最低 PHP 版本为 8.0。如果您有较旧的 PHP 版本，则 composer 命令将下载 googleads/googleads-php-lib 库的较旧版本。
• 此库依赖于 Composer。如果您尚未在计算机上安装它，请遵循Linux/Unix/OS X 的安装指南或Windows 的安装指南。在本指南的其余部分中，我们假设您正在使用 Linux/Unix/OS X 并且已全局安装 Composer，因此您的 Composer 作为 composer 可在命令行上使用。

入门

将示例 Ad Manager adsapi_php.ini 复制到您的 主目录，并在下载库之前填写所需属性。此库通过使用 EnvironmentalVariables::getHome() 使用计算机的主目录。

下载此库

如下所述，有三种下载此库的方法。

注意

• 如果您在已安装的应用程序流程之前没有 OAuth2 凭证，则需要examples/Auth/GetRefreshToken.php。在这种情况下，使用 composer require 不是选项，因为没有与库一起下载示例文件。
• 我们的示例旨在通过命令行运行，而不是作为网页。 如果您将它们作为网页运行，结果可能无法正确显示。

使用 composer require

以下步骤将此库作为第三方库下载到您的项目中。Composer 将下载此库并将其存储在 vendor/ 目录下。示例不会通过此下载方法下载。

1. 使用 Composer 安装最新版本。

   $ composer require googleads/googleads-php-lib
   

2. 如果您还没有这样做，请遵循 入门。

3. 如果您还没有设置凭证，请遵循 设置 OAuth2 凭证。

4. 您现在可以使用此库。

使用 git clone

此方法适用于想要修改或为此库做出贡献（例如，提交拉取请求）或想要尝试我们的示例的人。此存储库中的所有文件都将下载。

1. 在命令提示符下运行 git clone https://github.com/googleads/googleads-php-lib.git。

2. 您将获得一个 googleads-php-lib 目录。通过运行 cd googleads-php-lib 导航到它。

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

4. 如果您还没有这样做，请遵循 入门。

5. 如果您还没有设置凭证，请遵循 设置 OAuth2 凭证。

6. 您现在可以使用库并运行任何您想要的示例。通过执行以下命令尝试 GetAllNetworks.php

   $ php examples/AdManager/v202211/NetworkService/GetAllNetworks.php
   

下载压缩的 tarball

此方法适用于只想使用此客户端库尝试 Ad Manager API 的人。tarball 解压后的目录将仅包含 examples/ 目录。

1. 在 版本发布页面 上，选择您想要尝试的版本。然后，在 下载 下，选择您选择的 tarball。tarball 的名称表示它属于哪个产品，例如，admanager-examples-vX.Y.Z.tar.gz。

2. 将您下载的文件解压到计算机上的任何位置。

3. 导航到解压后的目录（例如，admanager-examples-vX.Y.Z）。

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

5. 如果您还没有这样做，请遵循 入门。

6. 如果您还没有设置凭证，请遵循 设置 OAuth2 凭证。

7. 您现在可以运行任何您想要的示例。通过执行以下命令尝试 GetAllNetworks.php

   $ php examples/AdManager/v202211/NetworkService/GetAllNetworks.php
   

设置您的 OAuth2 凭证

Ad Manager API 使用 OAuth2 作为身份验证机制。根据您的用例，遵循以下适当指南：

• 使用您自己的凭证
• 代表客户端操作

基本用法

通过查看 示例 是学习如何使用此库的最佳方式。

所有示例都旨在通过命令行运行，而不是通过网页。

如果您正在使用 32 位 PHP，您需要在运行示例之前将所有 intval() 实例更改为 floatval()。这是由于一些 ID 超过了 intval() 更改您的值时 PHP_INT_MAX 的 32 位。此外，在编写您自己的代码时，请勿对任何明确为整数的属性应用 intval()。

以下是从 GetAllNetworks.php 示例中的代码片段，它为您提供了如何使用此库的思路。

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

$session = (new AdManagerSessionBuilder())->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

$adManagerServices = new ServiceFactory();

$networkService = $adManagerServices->createNetworkService($session);

$networks = $networkService->getAllNetworks();

// Do something with the $networks.

构建器的 fromFile() 方法默认在您的家目录中查找 adsapi_php.ini 文件。如果您想将此文件存储在另一个目录中，请传递文件的路径作为参数。例如

fromFile('/config/myprops.ini')

强烈建议您使用 adsapi_php.ini 文件。但是，如果您不想使用或无法使用，您可以使用 OAuth2 令牌和广告会话构建器来设置相同的信息。请参阅构建器以获取详细信息

• OAuth2TokenBuilder
• AdManagerSessionBuilder

名称是保留PHP关键字的WSDL对象

一些WSDL枚举值的名称是保留的PHP关键字，在用作PHP常量名称时需要修改。例如，AND 和 DEFAULT 分别生成为 AND_VALUE 和 DEFAULT_VALUE。

日志记录

此库符合PSR-3日志记录规范，并为Ad Manager提供了以下日志记录器：

• SOAP日志记录器
• 报告下载器日志记录器

通常，每个日志记录器都会为事件（例如SOAP API调用）记录摘要和调试消息。消息记录的级别取决于事件是否成功。

配置日志记录

默认情况下，库中的每个日志记录器都使用STDERR在单独的通道上记录日志，使用Monolog StreamHandler。

您可以在adsapi_php.ini文件中配置这些默认日志记录器的某些选项。

[LOGGING]
; Optional logging settings.
soapLogFilePath = "path/to/your/soap.log"
soapLogLevel = "NOTICE"

如果您需要进一步自定义日志记录，您可以在Ad Manager会话构建器中提供实现了LoggerInterface的日志记录器来完全指定自己的日志记录器。

$session = (new AdManagerSessionBuilder())
    ...
    ->withSoapLogger(new MyCustomSoapLogger())
    ->withReportDownloaderLogger(new MyCustomReportDownloaderLogger())
    ->build();

工具

我们在此客户端库中提供了一些工具，帮助您更方便地使用Ad Manager API中的功能。

报告

在下载报告时，您可以使用stream_context键设置额外的流上下文选项，以满足您的需求（例如，如以下示例中所示增加超时）。有关详细信息，请参阅Guzzle常见问题解答。

$options = [
    'stream_context' => [
        'http' => ['timeout' => 120]
    ]
];
$requestOptionsFactory = new RequestOptionsFactory($session, $options);
$reportDownloader = new ReportDownloader($session, $requestOptionsFactory);

SSL CA文件

PHP自动将verify_peer设置为true，并将默认情况下尽可能找到系统中最合适的CA包。但是，并非所有系统都拥有已知CA包（例如Windows）。此库尝试使用Guzzle的default_ca_bundle()在您的系统上定位CA包。

如果此库无法在您的系统上找到CA包，您将收到类似以下错误消息

cURL error 60: SSL certificate problem: unable to get local issuer certificate.

CA文件问题也可能导致类似错误

Fatal error: Uncaught SoapFault exception: [WSDL] SOAP-ERROR: Parsing WSDL:
Couldn't load from
'https://ads.google.com/apis/ads/publisher/v202211/ActivityService?wsdl' :
failed to load external entity
"https://ads.google.com/apis/ads/publisher/v202211/ActivityService?wsdl

为了修复这些问题，请参阅故障排除CA文件问题的步骤。

文档

此库的PHPDoc可以在此存储库的gh-pages分支中找到。您可以在此处查看Ad Manager API站点。

有关Ad Manager API的一般文档，可以在我们的Google开发者网站上找到。

编码风格

我们使用PSR-2作为编码风格标准。假设您位于项目的根目录，要检查编码风格违规，请运行

vendor/bin/phpcs src --standard=phpcs_ruleset.xml -np

要自动修复（可修复的）编码风格违规，请运行

vendor/bin/phpcbf src --standard=phpcs_ruleset.xml

获取支持

对于客户端库特定的错误报告、功能请求和补丁，请在问题跟踪器上创建问题。

关于通用Ad Manager API的问题、错误报告或功能请求，请发布到Ad Manager API论坛。

公告和更新

有关通用Ad Manager API和客户端库的更新和新闻，您可以关注日落公告邮件列表，并依赖弃用计划。