本頁面由 Cloud Translation API 翻譯而成。

GAPIC

Google Ads API PHP 用戶端程式庫 src/Google/Ads/GoogleAds/vX 目錄中的原始碼 (其中 X 為 Google Ads API 版本) 會根據發布的 proto 檔案自動產生 GAPIC (Generated API 用戶端) Gennerator。

接著修改產生的原始碼，納入對特徵和類別的參照，並使用 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 第 2 版程式碼中產生。

圖案 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 第 2 版原始碼中產生的 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 第 1 版和第 2 版呼叫 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])
    ])
);