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/ (例如 V26)，而對應的要求和回應訊息類別 (例如 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：使用流暢 setter 的靜態建構方法

$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()，您必須使用 setter 或陣列建構函式建構要求物件。

模式 1：流暢的 setter (建議)

$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])
    ])
);