GAPIC

ซอร์สโค้ดในไดเรกทอรี src/Google/Ads/GoogleAds/vX ของไลบรารีไคลเอ็นต์ PHP ของ Google Ads API โดยที่ X คือเวอร์ชัน Google Ads API จะสร้างขึ้นโดยอัตโนมัติด้วยโปรแกรมสร้าง GAPIC (ไคลเอ็นต์ API ที่สร้างขึ้น) โดยอิงจากไฟล์โปรโตที่เผยแพร่

จากนั้นซอร์สโค้ดที่สร้างขึ้นจะได้รับการแก้ไขให้มีการอ้างอิงลักษณะและคลาสที่จำเป็นต่อการสร้างไคลเอ็นต์บริการที่ทำงานร่วมกับ Google Ads API โดยใช้คลาส GoogleAdsClient ซึ่งสร้างขึ้นโดยการเรียกใช้ GoogleAdsClientBuilder::build() ทั้ง GoogleAdsClient และ GoogleAdsClientBuilder เป็นชั้นเรียนที่สร้างขึ้นด้วยตนเองซึ่งอยู่ใน src/Google/Ads/GoogleAds/Lib/vX/

ซอร์สโค้ด GAPIC v2

ตั้งแต่เวอร์ชัน v20.1.0 ไลบรารีของไคลเอ็นต์ยังมีซอร์สโค้ด GAPIC เวอร์ชันใหม่ใน src/Google/Ads/GoogleAds/vX ซึ่งรองรับการส่งออบเจ็กต์คำขอไปยังเมธอดของไคลเอ็นต์บริการ เวอร์ชันใหม่นี้ที่เรียกว่า GAPIC v2 ยังช่วยเตรียมความพร้อมสำหรับฟีเจอร์ใหม่ๆ ในอนาคตด้วย ซอร์สโค้ด GAPIC เวอร์ชันก่อนหน้า GAPIC v1 ยังคงสร้างขึ้นและรวมอยู่กับแต่ละรุ่นจนถึงสิ้นปี 2023

ไลบรารีไคลเอ็นต์ PHP ของ Google Ads API ให้คุณเลือกเวอร์ชันที่จะลิงก์กับ GoogleAdsClient โดยใช้การตั้งค่าการกำหนดค่า useGapicV2Source เมื่อตั้งค่านี้เป็น true ไลบรารีของไคลเอ็นต์จะสร้างออบเจ็กต์ GoogleAdsClient ที่สร้างไคลเอ็นต์บริการ GAPIC v2

สถานที่ของชั้นเรียนที่สร้างขึ้น

ต่อไปนี้เป็นข้อแตกต่างของตำแหน่งไฟล์ระหว่างเวอร์ชัน GAPIC สำหรับคลาส 2 ประเภท

ไคลเอ็นต์ที่ GAPIC สร้างขึ้นและไฟล์ที่เกี่ยวข้อง GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
GAPIC v2: ไม่มี ระบบจะสร้างเฉพาะไฟล์ที่ผ่านการประมวลผลแล้วเท่านั้น
ไคลเอ็นต์หลังการประมวลผล GAPIC v1 
src/Google/Ads/GoogleAds/VX/Services/
GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

การใช้งาน

GAPIC v1 กำหนดให้คุณต้องส่งพารามิเตอร์คำขอแต่ละรายการไปยังเมธอดโดยตรง ในขณะที่ GAPIC v2 กำหนดให้คุณส่งออบเจ็กต์คำขอแทน โปรดทราบว่าในบางกรณี คุณสามารถสร้างออบเจ็กต์คำขอได้มากกว่า 1 วิธีเนื่องจาก GAPIC v2 จะสร้างเมธอดที่สะดวกชื่อว่า build() สำหรับการส่งผ่านพารามิเตอร์ที่ required ด้วย

ตัวอย่าง 1.1: เมธอดที่มีพารามิเตอร์ที่จำเป็น

โค้ดตัวอย่างต่อไปนี้จะเปรียบเทียบการเรียกใช้ CampaignService::mutate() ใน GAPIC v1 และ v2 โปรดทราบว่าพารามิเตอร์ทั้งหมด ($customerId และ $operations) เป็นพารามิเตอร์ที่จําเป็น ดังนั้น build() ที่ยอมรับพารามิเตอร์ทั้ง 2 รายการจะสร้างขึ้นในโค้ด GAPIC v2

รูปแบบ 1 GAPIC v1 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    $customerId,
    $campaignOperations
);
GAPIC v2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
      $customerId,
      $campaignOperations
    )
);
รูปแบบ 2 GAPIC v1 
N/A
GAPIC v2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

ตัวอย่างที่ 1.2: เมธอดที่มีพารามิเตอร์ที่จำเป็นและพารามิเตอร์ที่ไม่บังคับ

โค้ดตัวอย่างต่อไปนี้เปรียบเทียบการเรียกใช้ GoogleAdsServiceClient::search() ใน GAPIC v1 และ v2 ในตัวอย่างนี้ build() ที่สร้างขึ้นในซอร์สโค้ด GAPIC v2 ยอมรับพารามิเตอร์เพียง 2 รายการ ($customerId และ $query) เนื่องจากเป็นพารามิเตอร์ที่จำเป็น หากต้องการตั้งค่าขนาดหน้าเว็บ ซึ่งเป็นพารามิเตอร์ที่ไม่บังคับ คุณต้องตั้งค่าขนาดอย่างชัดแจ้งโดยใช้ setPageSize() หรือส่งผ่านพารามิเตอร์ทั้งหมดพร้อมกันไปยังตัวสร้าง SearchGoogleAdsRequest ตามที่แสดงในรูปแบบ 3

รูปแบบ 1 GAPIC v1 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['pageSize' => self::PAGE_SIZE]
);
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setPageSize(self::PAGE_SIZE)
);
รูปแบบ 2 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setPageSize(self::PAGE_SIZE);
$response = $googleAdsServiceClient->search($request);
รูปแบบ 3 GAPIC v1 
N/A
GAPIC v2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'page_size' => self::PAGE_SIZE
]);
$response = $googleAdsServiceClient->search($request);

ตัวอย่างที่ 2: เมธอดที่มีเฉพาะพารามิเตอร์ที่ไม่บังคับเท่านั้น

เปรียบเทียบการเรียกใช้ GeoTargetConstantServiceClient::suggestGeoTargetConstants() ใน GAPIC v1 และ v2 เนื่องจากพารามิเตอร์ทั้งหมดของ GeoTargetConstantServiceClient::suggestGeoTargetConstants() นั้นไม่บังคับ ดังนั้นในกรณีนี้ ระบบจะไม่สร้าง build() ในซอร์สโค้ด GAPIC v2 คุณจึงต้องสร้างออบเจ็กต์คำขอด้วยตัวเอง

รูปแบบ 1 GAPIC v1 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants([
    'locale' => $locale,
    'countryCode' => $countryCode,
    'locationNames' => new LocationNames(['names' => $locationNames])
]);
GAPIC v2 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);
รูปแบบ 2 GAPIC v1 
N/A
GAPIC v2 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);