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

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

דוגמאות

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

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

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

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

משתני סביבה

הזינו למטה את פרטי הכניסה והמזהים של החשבון, ואז מעתיקים ומדביקים אותם במסוף כדי להגדיר את משתני הסביבה שייעשה בהם שימוש בדוגמאות הבאות. המדריך 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 ופועלות עם אותם משתני סביבה שמפורטים במדריך הזה. השאילתה האינטראקטיבית שלנו Builder Tool גם משאב מצוין ליצירת שאילתות מותאמות אישית באופן אינטראקטיבי.

חלוקה לדפים

השיטה 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, כל הפעולות בבקשה יצליחו אך ורק אם כולן תקינות.

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

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

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

ה-method 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 של פיקסל אחד.

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

שיטות אחרות

נסה בעצמך!