GAPIC

Mã nguồn trong thư mục src/Google/Ads/GoogleAds/VX của thư viện ứng dụng Google Ads API PHP (trong đó X là số phiên bản Google Ads API) được tạo tự động bằng Trình tạo GAPIC (Ứng dụng API được tạo), dựa trên các tệp proto đã xuất bản.

Sau đó, mã nguồn được tạo sẽ được sửa đổi để chứa các tham chiếu đến các đặc điểm và lớp cần thiết để tạo các ứng dụng dịch vụ hoạt động với Google Ads API bằng cách sử dụng lớp GoogleAdsClient, được tạo bằng cách gọi GoogleAdsClientBuilder::build(). Cả GoogleAdsClient và GoogleAdsClientBuilder đều là các lớp được duy trì theo cách thủ công nằm trong src/Google/Ads/GoogleAds/Lib/VX/.

Vị trí lớp được tạo

Các ứng dụng dịch vụ sau khi xử lý nằm trong src/Google/Ads/GoogleAds/VX/Services/Client/ (ví dụ: V26) và các lớp thông báo yêu cầu và phản hồi tương ứng (chẳng hạn như MutateCampaignsRequest và SearchGoogleAdsRequest) nằm trong src/Google/Ads/GoogleAds/VX/Services/. Các bản phát hành API nhỏ (chẳng hạn như v25.1) được tạo bên trong thư mục phiên bản lớn (V25).

Cách sử dụng

Bạn phải tạo một đối tượng yêu cầu và truyền đối tượng đó đến ứng dụng dịch vụ mà bạn muốn sử dụng. Tuỳ thuộc vào việc tham số là bắt buộc hay không bắt buộc, bạn có nhiều cách để tạo đối tượng yêu cầu, bao gồm cả phương thức nhà máy build() tĩnh để truyền tham số bắt buộc.

Ví dụ 1.1: Phương thức có tham số bắt buộc

Mã mẫu sau đây cho biết cách gọi CampaignServiceClient::mutateCampaigns(). Vì cả $customerId và $campaignOperations đều là các tham số bắt buộc, nên một phương thức nhà máy build() tĩnh chấp nhận cả hai tham số sẽ được tạo trong lớp yêu cầu.

Mẫu 1: Phương thức tạo tĩnh (nên dùng)

$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
        $customerId,
        $campaignOperations
    )
);

Mẫu 2: Phương thức setter linh hoạt

$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

Ví dụ 1.2: Các phương thức có tham số bắt buộc và không bắt buộc

Mã mẫu sau đây gọi GoogleAdsServiceClient::search(). Trong ví dụ này, phương thức build() được tạo chỉ chấp nhận hai tham số ($customerId và $query) vì đây là các tham số bắt buộc. Để yêu cầu tổng số kết quả khớp với truy vấn bỏ qua mệnh đề LIMIT, bạn có thể đặt rõ ràng bằng setReturnTotalResultsCount(). Ngoài ra, bạn có thể truyền tất cả tham số cùng nhau trong một mảng liên kết đến hàm khởi tạo của SearchGoogleAdsRequest, như minh hoạ trong Mẫu 3.

Mẫu 1: Phương thức xây dựng tĩnh với phương thức setter linh hoạt

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

Mẫu 2: Phương thức setter linh hoạt

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setReturnTotalResultsCount(true);
$response = $googleAdsServiceClient->search($request);

Mẫu 3: Hàm khởi tạo mảng

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$request = new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'return_total_results_count' => true
]);
$response = $googleAdsServiceClient->search($request);

Ví dụ 2: Phương thức chỉ có tham số không bắt buộc

Ví dụ này cho thấy cách gọi GeoTargetConstantServiceClient::suggestGeoTargetConstants(). Vì tất cả tham số của GeoTargetConstantServiceClient::suggestGeoTargetConstants() đều không bắt buộc, nên build() không được tạo trong mã nguồn trong trường hợp này. Bạn phải tạo đối tượng yêu cầu bằng cách sử dụng phương thức setter hoặc hàm khởi tạo mảng.

Mẫu 1: Phương thức setter linh hoạt (nên dùng)

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);

Mẫu 2: Hàm khởi tạo mảng

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);