דוגמאות

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

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

כל הדוגמאות הבאות מיועדות להעתקה והדבקה במעטפת bash באמצעות הפקודה curl.

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

משתני סביבה

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

API_VERSION="19"
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

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

המדריך מתכונים לשאילתות מכיל דוגמאות רבות לדיווח שתואמות לחלק מהמסכים שמוגדרים כברירת מחדל ב-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'

Mutates

אפשר לשלוח כמה פעולות mutate (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 לשיטה 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}" \

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

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

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

משתמשים בכלי שורת הפקודה base64 (חלק מ-GNU core utilities) כדי לקודד תמונה GIF בגודל פיקסל אחד.

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'
      }
    }
  }
]
}"
הקודם
שיטות אחרות
הבא
נסה בעצמך!