דף זה תורגם על ידי Cloud Translation API.

GAPIC

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

לאחר מכן קוד המקור שנוצר משתנה כך שהוא מכיל הפניות לתכונות ולמחלקות, שנדרשות ליצירת לקוחות השירות שפועלים עם 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, שתומכת בהעברת אובייקט בקשה ל-methods של לקוחות השירות. הגרסה החדשה, שנקראת GAPIC v2, משמשת גם כהכנה לתכונות חדשות בעתיד. קוד המקור הקודם של GAPIC, GAPIC v1, עדיין נוצר ונכלל בכל גרסה עד סוף 2023.

ספריית הלקוח של 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

ב-GAPIC v1 צריך להעביר כל פרמטר בקשה ישירות ל-method, ואילו ב-GAPIC v2 צריך להעביר אובייקט בקשה. שימו לב שבמקרים מסוימים יש יותר מדרך אחת ליצור אובייקט בקשה, כי GAPIC v2 יוצר גם שיטה נוחה בשם 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 בגרסאות 1 ו-v2. בדוגמה הזו, ה-build() שנוצר בקוד המקור של GAPIC v2 מקבל רק שני פרמטרים ($customerId ו-$query) כי הם פרמטרים נדרשים. כדי לבקש את המספר הכולל של התוצאות שתואמות לשאילתה בהתעלמות מהסעיף LIMIT, צריך להגדיר אותו באופן מפורש באמצעות setReturnTotalResultsCount(). לחלופין, אפשר להעביר את כל הפרמטרים יחד ל-constructor של SearchGoogleAdsRequest, כפי שמוצג בתבנית 3.

דפוס 1

GAPIC v1

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    $customerId,
    $query,
    ['returnTotalResultsCount' => true]
);

GAPIC v2

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->search(
    SearchGoogleAdsRequest::build($customerId, $query)
        ->setReturnTotalResultsCount(true)
);

דפוס 2

GAPIC v1

N/A

GAPIC v2

$googleAdsServiceClient
    = $googleAdsClient->getGoogleAdsServiceClient();
$request = (new SearchGoogleAdsRequest())
    ->setCustomerId($customerId)
    ->setQuery($query)
    ->setReturnTotalResultsCount(true);
$response = $googleAdsServiceClient->search($request);

דפוס 3

GAPIC v1

N/A

GAPIC v2

$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 ו-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])
    ])
);