GAPIC

קוד המקור ב-src/Google/Ads/GoogleAds/vX ספרייה של ספריית הלקוח של Google Ads API ב-PHP, שבה X הוא Google Ads API של Google, נוצרת באופן אוטומטי באמצעות GAPIC (לקוח API שנוצר) Generator, על סמך פורסם פרוטו .

לאחר מכן קוד המקור שנוצר משתנה כך שיכלול הפניות לתכונות המחלקות שנדרשות כדי ליצור את לקוחות השירות שעובדים עם Google Ads API באמצעות הכיתה GoogleAdsClient, שנוצרה באמצעות התקשרות GoogleAdsClientBuilder::build(). גם GoogleAdsClient וגם GoogleAdsClientBuilder הן כיתות שנוצרו באופן ידני ונמצאות ב- src/Google/Ads/GoogleAds/Lib/vX/.

קוד מקור של GAPIC גרסה 2

החל מגרסה v20.1.0, ספריית הלקוח כולל גם גרסה חדשה של קוד המקור של GAPIC src/Google/Ads/GoogleAds/vX שתומך בהעברת אובייקט בקשה לשירות של הלקוחות שיטות. הגרסה החדשה הזו, שנקראת GAPIC v2, משמשת גם כהכנה כדי לקבל גישה לתכונות חדשות בעתיד. קוד המקור הקודם של GAPIC, GAPIC v1, הוא עדיין נוצרו ונכללים בכל גרסה עד סוף 2023.

ספריית הלקוח של Google Ads API PHP מאפשרת לבחור את הגרסה שאליה רוצים לקשר GoogleAdsClient באמצעות הגדרת התצורה useGapicV2Source. כשההגדרה הזו מוגדרת לערך true, ספריית הלקוח יוצרת אובייקט GoogleAdsClient שיוצר לקוחות השירות של GAPIC v2.

מיקומי הכיתה שנוצרו

ההבדלים במיקומים של הקבצים בין גרסאות GAPIC של שני סוגי מחלקות:

לקוחות שנוצרו על ידי GAPIC וקבצים קשורים GAPIC גרסה 1 
src/Google/Ads/GoogleAds/VX/Services/Gapic/
 GAPIC v2: אין. נוצר רק קובץ שעבר עיבוד.
לקוחות שעברו עיבוד GAPIC גרסה 1 
src/Google/Ads/GoogleAds/VX/Services/
 GAPIC v2 
src/Google/Ads/GoogleAds/VX/Services/Client/

שימוש

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

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

הקוד לדוגמה הבא משווה את הקריאה ל-CampaignService::mutate() ב-GAPIC v1 ו-v2. חשוב לשים לב שכל הפרמטרים ($customerId ו-$operations) לכן הפונקציה build() שמקבלת את שני הפרמטרים נוצרת בקוד GAPIC v2.

דפוס 1 GAPIC גרסה 1 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    $customerId,
    $campaignOperations
);
GAPIC גרסה 2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
      $customerId,
      $campaignOperations
    )
);
דפוס 2 GAPIC גרסה 1 
N/A
 GAPIC גרסה 2 
$campaignServiceClient
    = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

דוגמה 1.2: שיטות עם פרמטרים נדרשים ופרמטרים אופציונליים

הקוד לדוגמה הבא משווה את הקריאה ל-GoogleAdsServiceClient::search() ב- GAPIC בגרסאות 1 ו-2. בדוגמה הזו, השדה build() שנוצר ב-GAPIC קוד המקור בגרסה 2 מקבל רק שני פרמטרים ($customerId ו-$query) כי הם פרמטרים נדרשים. כדי לבקש את המספר הכולל של תוצאות שתואמות השאילתה מתעלמת מהסעיף LIMIT, צריך להגדיר אותה באופן מפורש באמצעות setReturnTotalResultsCount(). לחלופין, אפשר להעביר את כל הפרמטרים ל-constructor של SearchGoogleAdsRequest, כמו שמוצג בתבנית 3.

דפוס 1 GAPIC גרסה 1 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['returnTotalResultsCount' => true]
);
GAPIC גרסה 2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setReturnTotalResultsCount(true)
);
דפוס 2 GAPIC גרסה 1 
N/A
 GAPIC גרסה 2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setReturnTotalResultsCount(true);
$response = $googleAdsServiceClient->search($request);
דפוס 3 GAPIC גרסה 1 
N/A
 GAPIC גרסה 2 
$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'return_total_results_count' => true
]);
$response = $googleAdsServiceClient->search($request);

דוגמה 2: שיטות עם פרמטרים אופציונליים בלבד

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

דפוס 1 GAPIC גרסה 1 
$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 גרסה 1 
N/A
 GAPIC v2 
$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);