‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

דוגמאות

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

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

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

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

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

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

אתם צריכים גם פרויקט ב-Google Cloud (אפשר להשתמש בגישה לחשבון בדיקה) וחשבון ניהול ב-Google Ads עם חשבון לקוח אחד לפחות.

משתני סביבה

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

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

חיפוש

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

מחולק לדפים

ה-method‏ 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 "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'

סטרימינג

ה-method‏ 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 "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 "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 "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 "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 "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 "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 "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 "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 "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \

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

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

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

שינויים

יצירה

עדכונים

הסרה

כשלים חלקיים

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

ניהול חשבון

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

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

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

דוגמאות