Hàm GAPIC

Mã nguồn trong thư mục src/Google/Ads/GoogleAds/vX của thư viện ứng dụng PHP API Google Ads, trong đó X là phiên bản API Google Ads, đượ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 thông tin tham chiếu đến các đặc điểm và các lớp cần thiết để tạo các ứng dụng dịch vụ hoạt động với API Google Ads bằng cách sử dụng lớp GoogleAdsClient. Lớp này được tạo bằng cách gọi GoogleAdsClientBuilder::build(). Cả GoogleAdsClient và GoogleAdsClientBuilder đều được tạo thủ công trong src/Google/Ads/GoogleAds/Lib/vX/.

Mã nguồn GAPIC phiên bản 2

Kể từ phiên bản v20.1.0, thư viện ứng dụng cũng bao gồm một phiên bản mới của mã nguồn GAPIC trong src/Google/Ads/GoogleAds/vX. Phiên bản này hỗ trợ việc truyền đối tượng yêu cầu đến các phương thức của ứng dụng để phục vụ. Phiên bản mới này có tên là GAPIC v2, cũng đóng vai trò chuẩn bị cho các tính năng mới trong tương lai. Mã nguồn GAPIC trước đó là GAPIC v1 vẫn được tạo và đi kèm với mỗi bản phát hành cho đến hết năm 2023.

Thư viện ứng dụng PHP API Google Ads cho phép bạn chọn phiên bản sẽ được liên kết với GoogleAdsClient bằng cách sử dụng chế độ cài đặt cấu hình useGapicV2Source. Khi bạn đặt chế độ cài đặt này thành true, thư viện ứng dụng sẽ tạo một đối tượng GoogleAdsClient giúp tạo ứng dụng dịch vụ APIC v2.

Vị trí lớp học đã tạo

Dưới đây là sự khác biệt về vị trí tệp giữa các phiên bản GAPIC cho 2 loại lớp:

Ứng dụng do GAPIC tạo và các tệp liên quan GAPIC phiên bản 1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC phiên bản 2: Không có. Chỉ tạo tệp được xử lý sau.
Ứng dụng đã xử lý sau GAPIC phiên bản 1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC phiên bản 2 
src/Google/Ads/GoogleAds/VX/Services/Client/

Cách sử dụng

GAPIC v1 yêu cầu bạn truyền trực tiếp từng tham số yêu cầu đến một phương thức, trong khi GAPIC v2 yêu cầu bạn truyền đối tượng yêu cầu. Lưu ý rằng trong một số trường hợp, bạn có nhiều cách để tạo đối tượng yêu cầu vì GAPIC phiên bản 2 cũng tạo một phương thức thuận tiện tên là build() để truyền các tham số bắt buộc.

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

Mã mẫu sau đây so sánh lệnh gọi CampaignService::mutate() trong GAPIC v1 và v2. Lưu ý rằng tất cả tham số ($customerId và $operations) đều là tham số bắt buộc, vì vậy, build() chấp nhận cả hai tham số sẽ được tạo trong mã GAPIC v2.

Mẫu 1 GAPIC phiên bản 1 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    $customerId,
    $campaignOperations
);
GAPIC phiên bản 2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
      $customerId,
      $campaignOperations
    )
);
Mẫu 2 GAPIC phiên bản 1 
N/A
GAPIC phiên bản 2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

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

Mã mẫu sau đây so sánh lệnh gọi GoogleAdsServiceClient::search() trong GAPIC v1 và v2. Trong ví dụ này, build() được tạo trong mã nguồn GAPIC phiên bản 2 chỉ chấp nhận 2 tham số ($customerId và $query) vì chúng là các tham số bắt buộc. Để đặt kích thước trang (một tham số không bắt buộc), bạn phải đặt kích thước này một cách rõ ràng bằng cách sử dụng setPageSize(). Ngoài ra, bạn có thể truyền tất cả tham số cùng nhau đến hàm khởi tạo của SearchGoogleAdsRequest, như hiển thị trong mẫu 3.

Mẫu 1 GAPIC phiên bản 1 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['pageSize' => self::PAGE_SIZE]
);
GAPIC phiên bản 2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setPageSize(self::PAGE_SIZE)
);
Mẫu 2 GAPIC phiên bản 1 
N/A
GAPIC phiên bản 2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setPageSize(self::PAGE_SIZE);
$response = $googleAdsServiceClient->search($request);
Mẫu 3 GAPIC phiên bản 1 
N/A
GAPIC phiên bản 2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'page_size' => self::PAGE_SIZE
]);
$response = $googleAdsServiceClient->search($request);

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

So sánh lệnh gọi GeoTargetConstantServiceClient::suggestGeoTargetConstants() trong GAPIC v1 và v2. Vì tất cả tham số của GeoTargetConstantServiceClient::suggestGeoTargetConstants() là không bắt buộc, nên build() sẽ không được tạo trong mã nguồn GAPIC v2 trong trường hợp này – bạn phải tự tạo đối tượng yêu cầu.

Mẫu 1 GAPIC phiên bản 1 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants([
    'locale' => $locale,
    'countryCode' => $countryCode,
    'locationNames' => new LocationNames(['names' => $locationNames])
]);
GAPIC phiên bản 2 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);
Mẫu 2 GAPIC phiên bản 1 
N/A
GAPIC phiên bản 2 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);