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，並做為日後新功能的準備。直到 2023 年底為止，系統都會產生舊版 GAPIC 原始碼 (GAPIC v1)，並隨附於每個版本中。

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() 的所有參數皆為選用，因此在本例中，build() 不會在 GAPIC v2 原始碼中產生，您必須自行建立要求物件。

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