כששולחים קריאה ל-Google Ads API, צריך גם פרטי כניסה של OAuth 2.0 וגם קוד מפתח. אם אתם מבצעים קריאות API באמצעות חשבון ניהול ב-Google Ads, אתם צריכים לציין גם כותרת login-customer-id בכל בקשה. בדף הזה מוסבר איך להגדיר את הערכים האלה, ומתועדות בו כמה כותרות HTTP נוספות שספציפיות ל-API ונשלחות ומתקבלות כשמשתמשים בממשק REST.
פרטי כניסה של OAuth 2.0
ב-Google Ads API נעשה שימוש ב-OAuth 2.0 כדי לאשר בקשות ל-API. מערכת ADC תומכת בתהליך אימות משתמשים וגם בתהליך אימות חשבונות שירות באמצעות OAuth 2.0. פרטים נוספים זמינים במאמר בנושא OAuth 2.0 ב-Google Ads API.
אם אתם חדשים ב-Google APIs, אתם יכולים להשתמש ב-gcloud CLI או ב-OAuth 2.0 Playground כדי להתנסות בפרטי כניסה של OAuth 2.0 וב-Google Ads API לפני שתכתבו קוד לאפליקציה שלכם.
מומלץ להשתמש באחת מספריות OAuth 2.0 שזמינות בכתובת https://oauth.net/code/ כדי להטמיע את תהליכי העבודה של הרשאות OAuth 2.0. עם זאת, ריכזנו כאן את ההוראות לשימוש ב-curl למקרה שתרצו להטמיע אותו בעצמכם.
חשבונות שירות
פועלים לפי השלבים להגדרת פרויקט Google Cloud ל-Google Ads API. רושמים את כתובת האימייל של חשבון השירות ואת המפתח של חשבון השירות. לאחר מכן, פועלים לפי ההוראות הכלליות במדריך בנושא חשבונות שירות כדי להגדיר את חשבון השירות כך שתהיה לו גישה לחשבון Google Ads.
אימות משתמשים
פועלים לפי השלבים להגדרת פרויקט ב-Google Cloud Console ל-Google Ads API. רושמים את מזהה הלקוח ואת סוד הלקוח. לאחר מכן, פועלים לפי ההוראות לזרימת העבודה באפליקציה למחשב או לפי ההוראות לזרימת העבודה באפליקציית האינטרנט כדי ליצור אסימון רענון ואסימון גישה. ה-scope שצריך להשתמש בו
לגישה אל Google Ads API הוא https://www.googleapis.com/auth/adwords.
יצירת טוקנים חדשים של גישה
חשבונות שירות
אחרי שיש לכם את כתובת האימייל של חשבון השירות ואת המפתח של חשבון השירות, אתם יכולים לפעול לפי המדריך שימוש ב-OAuth 2.0 לאפליקציות שרת-אל-שרת כדי ליצור קבוצת טענות JWT, שאפשר להמיר אותה לאסימון גישה מסוג OAuth 2.0. חשוב לבחור בכרטיסייה HTTP/REST כשפועלים לפי המדריך. ה-OAuth 2.0 scope שבו צריך להשתמש כדי לגשת אל Google Ads API הוא https://www.googleapis.com/auth/adwords. בנוסף, אפשר לדלג על הפרמטר sub כשיוצרים את קבוצת התביעות של ה-JWT, כי שלבי ההגדרה מעניקים לחשבון השירות גישה ישירה לחשבון Google Ads, וכך נמנע הצורך להתחזות למשתמש ב-Google Ads.
לאחר מכן משתמשים באסימון הגישה בכותרת ה-HTTP Authorization של כל קריאה ל-Google Ads API:
GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
אימות משתמשים
אחרי שיש לכם מזהה לקוח, סוד לקוח וטוקן רענון של OAuth 2.0, אתם יכולים ליצור טוקן גישה חדש לשימוש בקריאות ל-API באמצעות כלי שורת הפקודה curl:
curl \
--data "grant_type=refresh_token" \
--data "client_id=CLIENT_ID" \
--data "client_secret=CLIENT_SECRET" \
--data "refresh_token=REFRESH_TOKEN" \
https://www.googleapis.com/oauth2/v3/tokenלאחר מכן משתמשים באסימון הגישה שמוחזר מבקשת curl בכותרת ה-HTTP Authorization של כל קריאה ל-Google Ads API:
GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
כותרות של בקשות
קוד מפתח
בנוסף, כדי לבצע קריאות ל-Google Ads API, צריך קוד מפתח. אם כבר יש לכם קוד מפתח, תוכלו למצוא אותו בכתובת https://ads.google.com/aw/apicenter. אם תתבקשו, היכנסו לחשבון הניהול ב-Google Ads. אם אין לכם טוקן, צריך לפעול לפי ההוראות להרשמה לטוקן למפתחים.
אתם צריכים לכלול את הערך של קוד המפתח בכותרת developer-token HTTP של כל קריאה ל-Google Ads API:
GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
מספר הלקוח להתחברות
בנוסף, כשמנהל שולח קריאות ל-Google Ads API לחשבון לקוח (כלומר, כשמתחברים כמנהל כדי לשלוח קריאות ל-API לאחד מחשבונות הלקוח שלו), צריך לספק גם את כותרת ה-HTTP login-customer-id. הערך הזה מייצג את מזהה הלקוח ב-Google Ads של חשבון הניהול ששולח את הקריאה ל-API.
הכללת הכותרת הזו שקולה לבחירת חשבון בממשק המשתמש של Google Ads אחרי הכניסה לחשבון או לחיצה על תמונת הפרופיל בפינה השמאלית העליונה של הדף. כשמציינים את מספר הלקוח, חשוב להסיר את כל המקפים (—).
לדוגמה: 1234567890 ולא 123-456-7890. במדריך למודל הגישה של Google Ads יש מידע נוסף על מספר הלקוח להתחברות.
GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
מספר הלקוח המקושר
הכותרת Linked customer ID (מספר לקוח מקושר) משמשת רק ספקים חיצוניים של שירותים לניתוח נתוני אפליקציות כשמעלים המרות לחשבון Google Ads מקושר. פרטים נוספים זמינים במדריך למבנה של קריאות ל-API.
...
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
linked-customer-id: LINKED_CUSTOMER_ID
כותרות תגובה
הכותרות הבאות מוחזרות בתגובות HTTP מה-API.
מזהה בקשה
request-id היא מחרוזת שמזהה באופן ייחודי את בקשת ה-API. כשמבצעים ניפוי באגים או פותרים בעיות שקשורות לקריאות ספציפיות ל-API, חשוב שיהיה לכם את המזהה request-id בהישג יד כדי לפנות לתמיכת המפתחים של Google.
request-id: 2a5Cj89VV7CNhya1DZjjrC