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

דוגמאות

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

דוגמאות קוד מפורטות יותר זמינות במאגר GitHub של דוגמאות קוד ל-REST.

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

לדוגמה, בדף העזר של GoogleAdsService.Search מוצגים גופי הבקשה והתגובה של השיטה Search.

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

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

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

משתני סביבה

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

API_VERSION="22"
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 example.

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'
      }
    }
  }
]
}"

שגיאות נפוצות

נסה בעצמך!

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

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

משתני סביבה

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

חיפוש

עימוד

curl

GAQL

סטרימינג

curl

GAQL

שינוי

יצירה

עדכונים

הסרה

כשלים חלקיים

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

ניהול חשבון

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

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

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

דוגמאות