Hàm GAPIC

Mã nguồn trong thư mục src/Google/Ads/GoogleAds/vX của thư viện ứng dụng PHP cho API Google Ads (trong đó X là phiên bản của 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à lớp cần thiết để tạo ứng dụng dịch vụ hoạt động với API Google Ads 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 tạo theo cách thủ công nằm 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 một đối tượng yêu cầu đến các phương thức của ứng dụng dịch 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 đó, GAPIC phiên bản 1, 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 của API Google Ads cho phép bạn chọn phiên bản sẽ 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 để tạo các ứng dụng dịch vụ GCC phiên bản 2.

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

Sau đâ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:

Các ứng dụng do GAPIC tạo và các tệp liên quan GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: Không có. Chỉ có tệp hậu xử lý mới được tạo ra.
Ứng dụng được xử lý hậu kỳ 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 chuyển đối tượng yêu cầu. Xin lưu ý rằng trong một số trường hợp, bạn có nhiều cách để tạo một đố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 có tên là build() để 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

Mã mẫu sau đây so sánh cách gọi CampaignService::mutate() trong GAPIC phiên bản 1 và phiên bản 2. Xin lưu ý rằng tất cả cá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 phiên bản 2.

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 việc gọi GoogleAdsServiceClient::search() trongGAPIC phiên bản 1 và phiên bản 2. Trong ví dụ này, build() được tạo trong mã nguồn GAPIC phiên bản 2 chỉ chấp nhận hai tham số ($customerId và $query) vì đó là các tham số bắt buộc. Để đặt kích thước trang (đây là tham số không bắt buộc), bạn phải đặt rõ ràng bằng cách sử dụng setPageSize(). Ngoài ra, bạn có thể truyền tất cả các tham số cùng nhau tới hàm khởi tạo của SearchGoogleAdsRequest, như minh hoạ 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 cách gọi GeoTargetConstantServiceClient::suggestGeoTargetConstants() trong GAPIC phiên bản 1 và phiên bản 2. 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 GAPIC phiên bản 2 – 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])
    ])
);