GAPIC

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

然后，对生成的源代码进行修改，添加对以下特征和类的引用：使用 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）都是必需参数，因此在 GAPIC v2 代码中生成接受这两个参数的 build()。

模式 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])
    ])
);