דוגמאות

המדריך כולל דוגמאות לקריאה ישירה לנקודות הקצה ב-REST, ללא שימוש בספריית לקוח.

דרישות מוקדמות

את כל הדוגמאות הבאות אפשר להעתיק ולהדביק ל-bash Shell באמצעות הפקודה curl.

נדרש גם אסימון מפתח, גישה לחשבון בדיקה וחשבון ניהול ב-Google Ads שמכיל לפחות חשבון לקוח אחד.

חשוב: בדוגמאות האלה אנחנו מניחים שהגישה שלכם לחשבון לקוח (CUSTOMER_ID) מתבצעת על ידי משתמש שיש לו הרשאת אדמין לחשבון ניהול (MANAGER_CUSTOMER_ID) שמנהל באופן ישיר את חשבון הלקוח. אם אתם רוצים לגשת ישירות לחשבון לקוח ספציפי, אפשר להשמיט את הכותרת login-customer-id או להגדיר אותה לערך זהה לזה של CUSTOMER_ID. שימו לב שלדוגמאות מסוימות, כמו יצירת חשבונות, נדרש חשבון ניהול.

משתני סביבה

צריך להזין למטה את פרטי הכניסה ואת המזהים של החשבון, ואז להעתיק ולהדביק אותם בטרמינל כדי להגדיר את משתני הסביבה שישמשו בדוגמאות הבאות. במדריך Authorization מוסבר איך ליצור אסימון גישה מסוג OAuth 2.0.

API_VERSION="17"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"

מזהי אובייקטים אופציונליים נוספים

חלק מהדוגמאות הבאות רלוונטיות לקמפיינים או לתקציבים קיימים. אם יש לכם מזהים של אובייקטים קיימים שאפשר להשתמש בהם בדוגמאות האלה, אתם צריכים להזין אותם בהמשך.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

אחרת, שני השינויים – יצירת דוגמאות יוצרים תקציב וקמפיין חדשים.

חיפוש

המדריך של Query Cookbook כולל הרבה דוגמאות דיווח שמתאימות לחלק ממסכי ברירת המחדל של Google Ads, ופועלים עם אותם משתני סביבה כמו במדריך הזה. הכלי האינטראקטיבי שלנו ליצירת שאילתות הוא גם משאב מצוין ליצירת שאילתות מותאמות אישית באופן אינטראקטיבי.

חלוקה לדפים

השיטה search משתמשת בחלוקה לדפים, עם גודל דף קבוע של 10,000 פריטים ו-page_token שמצוין לצד query.

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign.name,
    campaign_budget.amount_micros,
    campaign.status,
    campaign.optimization_score,
    campaign.advertising_channel_type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.bidding_strategy_type
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign.status != 'REMOVED'
",
"page_token":"${PAGE_TOKEN}"
}'

GAQL

SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'

סטרימינג

השיטה searchStream משדרת את כל התוצאות בתשובה אחת, ולכן השדה pageSize לא נתמך.

cURL

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign.name,
    campaign_budget.amount_micros,
    campaign.status,
    campaign.optimization_score,
    campaign.advertising_channel_type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.bidding_strategy_type
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign.status != 'REMOVED'
"
}'

GAQL

SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'

שינויים

אפשר לשלוח מספר פעולות שינוי (create, update או remove) בגוף בקשת JSON אחד על ידי אכלוס המערך operations.

יצירה

דוגמה זו יוצרת שני תקציבים משותפים של קמפיינים בבקשה אחת.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'name': 'My Campaign Budget #${RANDOM}',
      'amountMicros': 500000,
    }
  },
  {
    'create': {
      'name': 'My Campaign Budget #${RANDOM}',
      'amountMicros': 500000,
    }
  }
]
}"

הדוגמה הבאה משתמשת ב BUDGET_ID של תקציב קמפיין קיים; אפשר להעתיק ולהדביק מהפלט של השלב הקודם.

BUDGET_ID=BUDGET_ID

משאבים שמפנים למשאבים אחרים עושים זאת לפי שם המשאב. הקמפיין שנוצר בהמשך מתייחס ל-campaignBudget לפי שם המשאב שלו, בעל ערך המחרוזת.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'status': 'PAUSED',
      'advertisingChannelType': 'SEARCH',
      'geoTargetTypeSetting': {
        'positiveGeoTargetType': 'PRESENCE_OR_INTEREST',
        'negativeGeoTargetType': 'PRESENCE_OR_INTEREST'
      },
      'name': 'My Search campaign #${RANDOM}',
      'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}',
      'targetSpend': {}
    }
  }
]
}"

עדכונים

עדכון המאפיינים של אובייקטים קיימים באמצעות פעולות update. בדוגמה הבאה נעשה שימוש בקמפיין קיים. אפשר להעתיק ולהדביק מהפלט של השלב הקודם.

CAMPAIGN_ID=CAMPAIGN_ID

כל העדכונים צריכים לכלול את השדה updateMask, רשימה מופרדת בפסיקים של מאפייני ה-JSON שצריך לכלול בבקשה, שאותה צריך להחיל כעדכון. מאפיינים שרשומים ב-updateMask אבל לא נמצאים בגוף הבקשה נמחקים מאובייקט. המערכת מתעלמת ממאפיינים שלא מופיעים ב-updateMask אבל נמצאים בגוף הבקשה.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'update': {
      'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}',
      'name': 'A changed campaign name #${RANDOM}',
    },
    'updateMask': 'name'
  }
],
}"

הסרה

כדי להסיר אובייקטים, מציינים את שם המשאב שלהם כפעולה remove.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}'
  }
],
}"

כשלים חלקיים

אם הבקשה כוללת מספר פעולות, אפשר לציין partialFailure. אם הערך שלו הוא true, פעולות שבוצעו בהצלחה ושגיאות בהחזרת פעולות לא חוקיות. אם הערך שלו הוא false, כל הפעולות בבקשה יבוצעו בהצלחה, רק אם כולן תקינות.

בדוגמה הבאה נשתמש בקמפיין קיים. אפשר להעתיק ולהדביק פריטים מהפלט של Creates.

CAMPAIGN_ID=CAMPAIGN_ID

הבקשה הבאה מכילה שתי פעולות. הניסיון הראשון לשנות את שיטת הבידינג של הקמפיין שצוין, והקמפיין הבא מנסה להסיר קמפיין עם מזהה לא חוקי. הפעולה השנייה מובילה לשגיאה (מזהה הקמפיין לא חוקי) ובגלל שהשדה partialFailure מוגדר ל-false, גם הפעולה הראשונה נכשלת ושיטת הבידינג של הקמפיין הקיים לא מתעדכנת.

curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'partialFailure': false,
'operations': [
  {
    'update': {
      'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}',
      'manualCpc': {
        'enhancedCpcEnabled': false
      }
    },
    'updateMask': 'manual_cpc.enhanced_cpc_enabled'
  },
  {
    'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID'
  }
]
}"

פעולות קבוצתיות

השיטה googleAds:mutate תומכת בשליחת קבוצות של פעולות עם מספר סוגי משאבים. אפשר לשלוח פעולות רבות מסוגים שונים כדי לשרשר רצף של פעולות שצריך לבצע כקבוצה. קבוצת הפעולות מצליחה אם אף פעולה לא נכשלת או אם כולן נכשלות אם פעולה אחת נכשלת.

הדוגמה הזו ממחישה יצירה של תקציב קמפיין, קמפיין, קבוצת מודעות ומודעה יחד כקבוצה אחת של פעולות. כל פעולה רציפה תלויה בפעולה הקודמת. אם אחת מהן תיכשל, כל קבוצת הפעולות תיכשל.

מספרים שלמים שליליים (-1, -2, -3) משמשים כ-placeholders בשמות המשאבים, וממולאים באופן דינמי בזמן הריצה עם התוצאות מרצף הפעולות.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'mutateOperations': [
  {
    'campaignBudgetOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1',
        'name': 'My Campaign Budget #${RANDOM}',
        'deliveryMethod': 'STANDARD',
        'amountMicros': 500000,
        'explicitlyShared': false
      }
    }
  },
  {
    'campaignOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2',
        'status': 'PAUSED',
        'advertisingChannelType': 'SEARCH',
        'geoTargetTypeSetting': {
          'positiveGeoTargetType': 'PRESENCE_OR_INTEREST',
          'negativeGeoTargetType': 'PRESENCE_OR_INTEREST'
        },
        'name': 'My Search campaign #${RANDOM}',
        'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1',
        'targetSpend': {}
      }
    }
  },
  {
    'adGroupOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3',
        'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2',
        'name': 'My ad group #${RANDOM}',
        'status': 'PAUSED',
        'type': 'SEARCH_STANDARD'
      }
    }
  },
  {
    'adGroupAdOperation': {
      'create': {
        'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3',
        'status': 'PAUSED',
        'ad': {
          'responsiveSearchAd': {
            'headlines': [
              {
                'pinned_field': 'HEADLINE_1',
                'text': 'An example headline'
              },
              {
                'text': 'Another example headline'
              },
              {
                'text': 'Yet another headline'
              }
            ],
            'descriptions': [
              {
                'text': 'An example description'
              },
              {
                'text': 'Another example description'
              }
            ],
            'path1': 'all-inclusive',
            'path2': 'deals'
          },
          'finalUrls': ['https://www.example.com']
        }
      }
    }
  }
]
}"

ניהול החשבון

יצירת חשבונות

יוצרים חשבונות חדשים באמצעות השיטה createCustomerClient. שימו לב שבכתובת ה-URL נדרש מזהה של חשבון ניהול ולא מספר חשבון לקוח. חשבון לקוח חדש נוצר תחת חשבון הניהול.

curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'customerClient': {
  'descriptiveName': 'My Client #${RANDOM}',
  'currencyCode': 'USD',
  'timeZone': 'America/New_York'
}
}"

הצגת רשימה של חשבונות נגישים

משתמשים בבקשת GET פשוטה ל-method listAccessibleCustomers כדי לקבל רשימה של חשבונות Google Ads שאפשר לגשת אליהם באמצעות אסימון הגישה הנתון מסוג OAuth 2.0. בבקשה הזו אין להשתמש במספרים של חשבונות ניהול או חשבונות לקוח.

curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \

העלאת נכסים בינאריים

ה-method assets:mutate משמשת להעלאה ולניהול של נכסים. נתונים בינאריים, כמו תמונה, מקודדים כמחרוזת באמצעות קידוד base64 סטנדרטי עם מרווח פנימי. ניתן להשתמש בקידוד base64 רגיל או בטוח לכתובת URL, עם או בלי מרווח פנימי.

בדוגמה הזו מתבצעת קידוד של GIF בגודל פיקסל אחד כדי שהדוגמה תהיה תמציתית. בפועל, מטענים ייעודיים (payloads) של data גדולים הרבה יותר.

משתמשים בכלי שורת הפקודה base64 (חלק מתוכנות הליבה של GNU) כדי לקודד תמונת GIF של 1 פיקסל.

base64 1pixel.gif

הערך בקידוד base64 מצוין כמאפיין data בבקשת API.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'name': 'My image asset #${RANDOM}',
      'type': 'IMAGE',
      'imageAsset': {
        'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA'
      }
    }
  }
]
}"