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/ (לדוגמה, V25), והבקשה המתאימה ומחלקות הודעות התגובה (כמו MutateCampaignsRequest ו-SearchGoogleAdsRequest) נמצאות בתיקייה src/Google/Ads/GoogleAds/VX/Services/. גרסאות משניות של API (כמו v25.1) נוצרות בתוך ספריית הגרסה הראשית שלהן (V25).

שימוש

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

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

בדוגמת הקוד הבאה אפשר לראות איך מפעילים את CampaignServiceClient::mutateCampaigns(). מכיוון שגם $customerId וגם $campaignOperations הם פרמטרים נדרשים, נוצרת שיטת factory סטטית 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(). לחלופין, אפשר להעביר את כל הפרמטרים יחד במערך משויך אל בנאי המחלקה SearchGoogleAdsRequest, כמו בדוגמה 3.

תבנית 1: שיטת בנייה סטטית עם שיטות setter שוטפות

$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: שימוש בשיטות שרשור (מומלץ)

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