דוגמאות

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

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

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

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

משתני סביבה

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

API_VERSION="21"
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 יוצרות תקציב וקמפיין חדשים.

במדריך 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) משמשים כערכי placeholder בשמות המשאבים, והם מתמלאים באופן דינמי בזמן הריצה בתוצאות של רצף הפעולות.

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 בגודל פיקסל אחד מקודד כדי שהדוגמה תהיה תמציתית. בפועל, המטען הייעודי (payload) של data גדול הרבה יותר.

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