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/ 中手动创建的类。

GAPIC v2 源代码

从 v20.1.0 版开始，客户端库还在 src/Google/Ads/GoogleAds/vX 中添加了新版 GAPIC 源代码，该源代码支持将请求对象传递给服务客户端的方法。这一新版本名为 GAPIC v2，也为将来添加新功能做准备。之前的 GAPIC 源代码 GAPIC v1 仍会生成，并会包含在每个版本中，直至 2023 年底。

通过 Google Ads API PHP 客户端库，您可以使用配置设置 useGapicV2Source 选择要关联到 GoogleAdsClient 的版本。当此设置设为 true 时，客户端库会生成一个 GoogleAdsClient 对象，以创建 GAPIC v2 服务客户端。

生成的类位置

以下是这两个类类型的 GAPIC 版本在文件位置方面的差异：

GAPIC 生成的客户端和相关文件 GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2：无。只生成后处理文件。
后处理客户端 GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

用法

GAPIC v1 要求您将每个请求参数直接传递给某个方法，而 GAPIC v2 要求您传递一个请求对象。请注意，在某些情况下，您可以使用多种方法创建请求对象，因为 GAPIC v2 还会生成一个名为 build() 的便捷方法，用于传递必需参数。

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

以下示例代码比较了在 GAPIC v1 和 v2 中调用 CampaignService::mutate() 的过程。请注意，所有参数（$customerId 和 $operations）均为必需参数，因此接受这两个参数的 build() 会在 GAPIC v2 代码中生成。

模式 1 GAPIC v1 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    $customerId,
    $campaignOperations
);
GAPIC v2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
      $customerId,
      $campaignOperations
    )
);
模式 2 GAPIC v1 
N/A
GAPIC v2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

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

以下示例代码比较了在 GAPIC v1 和 v2 中调用 GoogleAdsServiceClient::search() 的过程。在本例中，在 GAPIC v2 源代码中生成的 build() 仅接受两个参数（$customerId 和 $query），因为它们是必需参数。如需设置页面大小（可选参数），您必须使用 setPageSize() 明确设置页面大小。或者，您也可以将所有参数一起传递给 SearchGoogleAdsRequest 的构造函数，如模式 3 所示。

模式 1 GAPIC v1 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['pageSize' => self::PAGE_SIZE]
);
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setPageSize(self::PAGE_SIZE)
);
模式 2 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setPageSize(self::PAGE_SIZE);
$response = $googleAdsServiceClient->search($request);
模式 3 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'page_size' => self::PAGE_SIZE
]);
$response = $googleAdsServiceClient->search($request);

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

比较了在 GAPIC v1 和 v2 中调用 GeoTargetConstantServiceClient::suggestGeoTargetConstants() 的操作。由于 GeoTargetConstantServiceClient::suggestGeoTargetConstants() 的所有参数都是可选的，因此在这种情况下，GAPIC v2 源代码中不会生成 build()，您必须自行创建请求对象。

模式 1 GAPIC v1 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants([
    'locale' => $locale,
    'countryCode' => $countryCode,
    'locationNames' => new LocationNames(['names' => $locationNames])
]);
GAPIC v2 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);
模式 2 GAPIC v1 
N/A
GAPIC v2 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);