GAPIC

Google Ads API PHP 用戶端程式庫的 src/Google/Ads/GoogleAds/VX 目錄中的原始碼 (其中 X 是 Google Ads API 版本號碼)，是根據已發布的 proto 檔案，使用 GAPIC (產生的 API 用戶端) 產生器自動產生。

接著，系統會修改產生的原始碼，使其包含使用 GoogleAdsClient 類別建立服務用戶端時所需的特徵和類別，這些服務用戶端會與 Google Ads API 搭配使用，而類別是透過呼叫 GoogleAdsClientBuilder::build() 建立。GoogleAdsClient 和 GoogleAdsClientBuilder 都是手動維護的類別，位於 src/Google/Ads/GoogleAds/Lib/VX/ 中。

產生的類別位置

後續處理的服務用戶端位於 src/Google/Ads/GoogleAds/VX/Services/Client/ (例如 V25)，而對應的要求和回應訊息類別 (例如 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：流暢設定器

$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：使用流暢設定器的靜態建構方法

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setReturnTotalResultsCount(true)
);

模式 2：流暢設定器

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

模式 1：流暢設定器 (建議)

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