GAPIC

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

จากนั้นจะปรับแต่งซอร์สโค้ดที่สร้างขึ้นให้มีการอ้างอิงไปยังลักษณะและคลาสที่จำเป็นในการสร้างไคลเอ็นต์บริการที่ทำงานกับ 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() เพื่อความสะดวกในการส่งพารามิเตอร์ที่จำเป็น

ตัวอย่างที่ 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])
    ])
);