GAPIC

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

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

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

לקוחות השירות שעברו עיבוד נמצאים ב-src/Google/Ads/GoogleAds/VX/Services/Client/ (לדוגמה, V26), והמחלקות התואמות של הודעות הבקשה והתגובה (כמו MutateCampaignsRequest ו-SearchGoogleAdsRequest) נמצאות ב-src/Google/Ads/GoogleAds/VX/Services/. גרסאות API משניות (כמו v25.1) נוצרות בתוך הספרייה של הגרסה הראשית (V25).

שימוש

צריך ליצור אובייקט בקשה ולהעביר אותו ללקוח השירות שבו רוצים להשתמש. בהתאם לפרמטרים הנדרשים או האופציונליים, יש כמה דרכים ליצור אובייקט בקשה, כולל שיטת מפעל סטטית build() להעברת פרמטרים נדרשים.

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

הקוד לדוגמה הבא מראה איך להפעיל את CampaignServiceClient::mutateCampaigns(). מכיוון שגם $customerId וגם $campaignOperations הם פרמטרים נדרשים, נוצרת במחלקת הבקשה שיטת מפעל סטטית build() שמקבלת את שני הפרמטרים.

תבנית 1: שיטת בנייה סטטית (מומלץ)

$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build(
        $customerId,
        $campaignOperations
    )
);

תבנית 2: פונקציות setter שוטפות

$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$request = (new MutateCampaignsRequest())
    ->setCustomerId($customerId)
    ->setCampaignOperations($campaignOperations);
$response = $campaignServiceClient->mutateCampaigns($request);

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

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

דפוס 1: שיטת בנייה סטטית עם מגדירים שוטפים

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

תבנית 2: פונקציות setter שוטפות

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

תבנית 3: בנאי מערך

$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$request = new SearchGoogleAdsRequest([
    'customer_id' => $customerId,
    'query' => $query,
    'return_total_results_count' => true
]);
$response = $googleAdsServiceClient->search($request);

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

בדוגמה הזו מוסבר איך להפעיל את GeoTargetConstantServiceClient::suggestGeoTargetConstants(). כל הפרמטרים של GeoTargetConstantServiceClient::suggestGeoTargetConstants() הם אופציונליים, ולכן build() לא נוצר בקוד המקור במקרה הזה – צריך לבנות את אובייקט הבקשה באמצעות פונקציות setter או בנאי המערך.

תבנית 1: פונקציות setter שוטפות (מומלץ)

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$request = (new SuggestGeoTargetConstantsRequest())
    ->setLocale($locale)
    ->setCountryCode($countryCode)
    ->setLocationNames(new LocationNames(['names' => $locationNames]));
$response =
    $geoTargetConstantServiceClient->suggestGeoTargetConstants($request);

תבנית 2: בנאי מערך

$geoTargetConstantServiceClient =
    $googleAdsClient->getGeoTargetConstantServiceClient();
$response = $geoTargetConstantServiceClient->suggestGeoTargetConstants(
    new SuggestGeoTargetConstantsRequest([
        'locale' => $locale,
        'country_code' => $countryCode,
        'location_names' => new LocationNames(['names' => $locationNames])
    ])
);