GAPIC

Google Ads API PHP 客户端库的 src/Google/Ads/GoogleAds/VX 目录中的源代码（其中 X 是 Google Ads API 版本号）是根据已发布的 proto 文件使用 GAPIC（生成的 API 客户端）生成器自动生成的。

然后，修改生成的源代码，使其包含使用 GoogleAdsClient 类（通过调用 GoogleAdsClientBuilder::build() 创建）创建与 Google Ads API 搭配使用的服务客户端所需的特性和类的引用。GoogleAdsClient 和 GoogleAdsClientBuilder 都是手动维护的类，位于 src/Google/Ads/GoogleAds/Lib/VX/ 中。

生成的类位置

后处理的服务客户端位于 src/Google/Ads/GoogleAds/VX/Services/Client/ 中（例如 V25），相应的请求和响应消息类（例如 MutateCampaignsRequest 和 SearchGoogleAdsRequest）位于 src/Google/Ads/GoogleAds/VX/Services/ 中。次要 API 版本（例如 v25.1）是在其主要版本目录 (V25) 内生成的。

用法

您必须创建一个请求对象，并将其传递给要使用的服务客户端。根据参数是必需还是可选，您可以通过多种方式创建请求对象，包括用于传递必需参数的静态 build() 工厂方法。

示例 1.1：包含必需参数的方法

以下示例代码展示了如何调用 CampaignServiceClient::mutateCampaigns()。由于 $customerId 和 $campaignOperations 都是必需参数，因此系统会在请求类中生成一个接受这两个参数的静态 build() 工厂方法。

模式 1：静态构建方法（推荐）

$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
        $customerId,
        $campaignOperations
    )
);

模式 2：流畅的 setter

$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

示例 1.2：包含必需参数和可选参数的方法

以下示例代码会调用 GoogleAdsServiceClient::search()。在此示例中，生成的 build() 方法仅接受两个参数（$customerId 和 $query），因为它们是必需参数。如需请求与查询匹配的结果总数（忽略 LIMIT 子句），您可以使用 setReturnTotalResultsCount() 显式设置该值。或者，您也可以将所有参数一起以关联数组的形式传递给 SearchGoogleAdsRequest 的构造函数，如模式 3 所示。

模式 1：使用流畅设置器的静态构建方法

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setReturnTotalResultsCount(true)
);

模式 2：流畅的 setter

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setReturnTotalResultsCount(true);
$response = $googleAdsServiceClient->search($request);

模式 3：数组构造函数

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$request = new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'return_total_results_count' => true
]);
$response = $googleAdsServiceClient->search($request);

示例 2：仅包含可选参数的方法

此示例展示了如何调用 GeoTargetConstantServiceClient::suggestGeoTargetConstants()。由于 GeoTargetConstantServiceClient::suggestGeoTargetConstants() 的所有形参都是可选的，因此在这种情况下，源代码中不会生成 build()，您必须使用设置器或数组构造函数来构造请求对象。

模式 1：流畅的设置器（推荐）

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);

模式 2：数组构造函数

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);