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 לשני סוגי המחלקות:

לקוחות שנוצרו על ידי 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/

Usage

בגרסה 1 של GAPIC עליכם להעביר כל פרמטר של בקשה ישירות לשיטה, ואילו ב-GAPIC v2 תצטרכו להעביר אובייקט בקשה במקום זאת. שימו לב שבמקרים מסוימים יש יותר מדרך אחת ליצור אובייקט בקשה, כי GAPIC בגרסה 2 יוצר גם שיטה נוחה בשם build() להעברת פרמטרים נדרשים.

דוגמה 1.1: שיטות עם פרמטרים נדרשים

הקוד לדוגמה הבא משווה בין הקריאה ל-CampaignService::mutate() ב-GAPIC בגרסה 1 וב-v2. שימו לב שכל הפרמטרים ($customerId ו-$operations) הם פרמטרים נדרשים, לכן השדה build() שמקבל את שני הפרמטרים נוצר בקוד 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 מקבל רק שני פרמטרים ($customerId ו-$query) כי הם פרמטרים נדרשים. כדי להגדיר גודל דף, שהוא פרמטר אופציונלי, צריך להגדיר אותו במפורש באמצעות setPageSize(). לחלופין, אפשר להעביר את כל הפרמטרים ביחד ל-builder של 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])
    ])
);