Hàm GAPIC

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

Sau đó, mã nguồn tạo ra được sửa đổi để chứa thông tin tham chiếu đến các đặc điểm và bắt buộc để 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 là các lớp học đượ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 hỗ trợ việc truyền một đối tượng yêu cầu đến dịch vụ của khách hàng . Phiên bản mới này, có tên là GAPIC v2, cũng đóng vai trò là bước chuẩn bị cho các tính năng mới trong tương lai. Mã nguồn GAPIC trước đây, GAPIC phiên bản 1, là vẫn được tạo và đi kèm trong 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 cần liên kết GoogleAdsClient bằng chế độ cài đặt cấu hình useGapicV2Source. Khi chế độ cài đặt này được đặt thành true, thư viện ứng dụng sẽ tạo một đối tượng GoogleAdsClient tạo Ứng dụng dịch vụ GAPIC 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 hai loại lớp:

Các ứ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ỉ 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 thông số yêu cầu đến một phương thức, trong khi GAPIC v2 yêu cầu bạn truyền một đối tượng yêu cầu. Lưu ý rằng trong 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 kể từ GAPIC v2 cũng tạo một phương thức thuận tiện có tên là build() để truyền bắt buộc tham số.

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

Mã mẫu sau đây so sánh việc gọi CampaignService::mutate() trong GAPIC v1 và v2. Xin lưu ý rằng tất cả tham số ($customerId và $operations) đều tham số bắt buộc, nên build() chấp nhận cả hai thông 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() trong GAPIC phiên bản 1 và phiên bản 2. Trong ví dụ này, build() được tạo trong GAPIC Mã nguồn v2 chỉ chấp nhận hai tham số ($customerId và $query) vì chúng là các tham số bắt buộc. Để yêu cầu tổng số kết quả khớp truy vấn bỏ qua mệnh đề LIMIT, bạn phải đặt mệnh đề rõ ràng bằng cách sử dụng setReturnTotalResultsCount() Ngoài ra, bạn có thể chuyển mọi thông số cùng vớ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,
    ['returnTotalResultsCount' => true]
);
GAPIC phiên bản 2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setReturnTotalResultsCount(true)
);
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)
    ->setReturnTotalResultsCount(true);
$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,
    'return_total_results_count' => true
]);
$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 tính năng gọi GeoTargetConstantServiceClient::suggestGeoTargetConstants() trong GAPIC phiên bản 1 và phiên bản 2. Vì tất cả thông số của GeoTargetConstantServiceClient::suggestGeoTargetConstants() là không bắt buộc, build() không được tạo trong mã nguồn GAPIC v2 trong trường hợp này — bạn 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])
    ])
);