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 đã tạo), dựa trên các tệp proto đã xuất bản.

Sau đó, mã nguồn đã tạo sẽ được sửa đổi để chứa các tham chiếu đến những đặc điểm và lớp cần thiết để tạo các ứng dụng khách dịch vụ hoạt động với Google Ads API bằng cách sử dụng lớp GoogleAdsClient do việc gọi GoogleAdsClientBuilder::build() tạo ra. 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ụ đã xử lý nằm trong src/Google/Ads/GoogleAds/VX/Services/Client/ (ví dụ: V25) 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 phụ (chẳng hạn như v25.1) được tạo 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 các tham số là bắt buộc hay không bắt buộc, bạn có nhiều cách để tạo một đối tượng yêu cầu, bao gồm cả phương thức tĩnh build() của nhà máy để truyền các tham số bắt buộc.

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

Đoạn 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 tĩnh build() sẽ được tạo trong lớp yêu cầu. Phương thức này chấp nhận cả hai tham số.

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: Fluent setter

$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 2 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 một cách rõ ràng bằng cách sử dụng setReturnTotalResultsCount(). Ngoài ra, bạn có thể truyền tất cả các tham số cùng nhau trong một mảng kết hợp đến hàm khởi tạo của SearchGoogleAdsRequest, như minh hoạ trong Mẫu 3.

Mẫu 1: Phương thức tạo tĩnh với các phương thức thiết lập trôi chảy

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

Mẫu 2: Fluent setter

$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ả cá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 các phương thức thiết lập hoặc hàm khởi tạo mảng.

Mẫu 1: Trình thiết lập trôi chảy (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])
    ])
);