זהירות: אתה צופה בתיעוד עבור ממשק ה-API ל-REST. רוב ספריות הלקוחות הרשמיות שלנו משתמשות ב-gRPC. פרטים נוספים זמינים במבוא ל-REST.

דף זה תורגם על ידי Cloud Translation API.

דוגמאות

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

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

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

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

משתני סביבה

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

API_VERSION="16"
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 משתמשת בעימוד, עם פרמטר pageSize שניתן להתאמה לצד 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 '{
"pageSize": 10,
"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'

סטרימינג

השיטה 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}" \

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

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

בדוגמה הזו מתבצע קידוד GIF של פיקסל אחד כדי שהדוגמה תהיה תמציתית. בפועל, מטענים ייעודיים (payloads) של 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'
      }
    }
  }
]
}"

שיטות אחרות

נסה בעצמך!