การตรวจสอบสิทธิ์และการให้สิทธิ์

Google Ads API ใช้โปรโตคอล OAuth 2.0 สำหรับการตรวจสอบสิทธิ์และการให้สิทธิ์เช่นเดียวกับ Google APIs อื่นๆ OAuth 2.0 ช่วยให้แอปไคลเอ็นต์ Google Ads API เข้าถึงบัญชี Google Ads ของผู้ใช้ได้โดยไม่ต้องจัดการหรือจัดเก็บข้อมูลการเข้าสู่ระบบของผู้ใช้

คู่มือนี้จะอธิบายวิธีกำหนดค่าไลบรารีของไคลเอ็นต์ Java สำหรับการตรวจสอบสิทธิ์ Google Ads API โดยใช้ขั้นตอน OAuth 2.0 ที่พบบ่อยที่สุด 3 รายการ พร้อมทั้งอธิบายข้อมูลเข้าสู่ระบบที่จำเป็น

หากต้องการเจาะลึกเกี่ยวกับรูปแบบการเข้าถึง Google Ads API โปรดอ่านคู่มือรูปแบบการเข้าถึง Google Ads

ข้อมูลเข้าสู่ระบบ

การเข้าถึง Google Ads API ต้องใช้ข้อมูลเข้าสู่ระบบ OAuth 2.0 และในบางกรณีต้องใช้รหัสลูกค้าที่เข้าสู่ระบบ

ข้อมูลเข้าสู่ระบบ OAuth 2.0

หากต้องการให้สิทธิ์ในฐานะผู้ใช้บัญชี Google ที่มีสิทธิ์เข้าถึงบัญชี Google Ads คุณต้องระบุชุดข้อมูลเข้าสู่ระบบ OAuth 2.0 ประเภทของข้อมูลเข้าสู่ระบบที่จำเป็นจะแตกต่างกันไปตามขั้นตอน OAuth 2.0 ที่ใช้

ไลบรารีรองรับขั้นตอน 3 แบบ ดังนี้

  • โฟลว์บัญชีบริการ
  • ขั้นตอนการตรวจสอบสิทธิ์ผู้ใช้รายเดียว
  • ขั้นตอนการตรวจสอบสิทธิ์ผู้ใช้หลายคนหนึ่งเครื่อง

ดูรายละเอียดเกี่ยวกับขั้นตอน OAuth ของ Google Ads API ได้ที่ภาพรวมของ OAuth และทำตามวิธีการสำหรับขั้นตอนที่ตรงกับความต้องการของคุณมากที่สุดเพื่อรับข้อมูลเข้าสู่ระบบที่จำเป็น

รหัสลูกค้าที่เข้าสู่ระบบ

ระบุรหัสลูกค้าของบัญชีดูแลจัดการที่ให้สิทธิ์เข้าถึงบัญชีที่ใช้แสดงโฆษณา (ไม่บังคับ) คุณต้องระบุรหัสนี้หากเข้าถึงบัญชีลูกค้าผ่านบัญชีดูแลจัดการ ไม่จำเป็นต้องระบุบัญชีดูแลจัดการทั้งหมดในเส้นทางไปยังรหัสลูกค้า แต่ระบุเฉพาะรหัสผู้จัดการระดับบนสุดที่คุณใช้สำหรับสิทธิ์เข้าถึง ดูรายละเอียดเพิ่มเติมได้ที่เอกสารประกอบที่เกี่ยวข้อง

ในไลบรารีของไคลเอ็นต์ รหัสลูกค้าที่เข้าสู่ระบบจะระบุโดยคีย์ api.googleads.loginCustomerId ในไฟล์ ads.properties

การกำหนดค่า

คุณสามารถกำหนดค่าไลบรารีของไคลเอ็นต์ด้วยไฟล์ ads.properties, ตัวแปรสภาพแวดล้อม หรือแบบเป็นโปรแกรม คู่มือนี้มุ่งเน้นที่การใช้ไฟล์ ads.properties ดูรายละเอียดเกี่ยวกับตัวเลือกทั้งหมดได้ในคู่มือการกำหนดค่า

หากใช้ไฟล์ ads.properties ให้วางไว้ในไดเรกทอรีหน้าแรก ดังนี้ ~/ads.properties

เวิร์กโฟลว์ OAuth

เวิร์กโฟลว์ที่ใช้กันทั่วไปเมื่อทำงานกับ Google Ads API มีอยู่ 3 แบบ

โฟลว์บัญชีบริการ

เราขอแนะนำให้ใช้เวิร์กโฟลว์นี้หากเวิร์กโฟลว์ของคุณไม่จำเป็นต้องมีการโต้ตอบกับมนุษย์ เวิร์กโฟลว์นี้ต้องมีขั้นตอนการกำหนดค่า ซึ่งผู้ใช้จะเพิ่มบัญชีบริการลงในบัญชี Google Ads จากนั้นแอปจะใช้ข้อมูลเข้าสู่ระบบของบัญชีบริการเพื่อจัดการบัญชี Google Ads ของผู้ใช้ได้

เมื่อมีไฟล์ JSON ของคีย์ส่วนตัวแล้ว ให้เพิ่มข้อมูลต่อไปนี้ลงในไฟล์ ads.properties

api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

ดูข้อมูลเพิ่มเติมได้ที่คู่มือเวิร์กโฟลว์บัญชีบริการ

ขั้นตอนการตรวจสอบสิทธิ์ผู้ใช้รายเดียว

คุณสามารถใช้เวิร์กโฟลว์นี้ได้หากใช้บัญชีบริการไม่ได้ เวิร์กโฟลว์นี้ต้องมีการกำหนดค่า 2 ขั้นตอนดังนี้

  1. ให้สิทธิ์ผู้ใช้รายเดียวเข้าถึงบัญชีทั้งหมดที่จะจัดการโดยใช้ Google Ads API แนวทางที่พบบ่อยคือการให้สิทธิ์เข้าถึงบัญชีดูแลจัดการ Google Ads API แก่ผู้ใช้ และลิงก์บัญชี Google Ads เป้าหมายทั้งหมดภายใต้บัญชีดูแลจัดการนั้น
  2. ผู้ใช้เรียกใช้เครื่องมือบรรทัดคำสั่ง เช่น gcloud CLI หรือตัวอย่างโค้ด GenerateUserCredentials เพื่อให้สิทธิ์แอปของคุณจัดการบัญชี Google Ads ทั้งหมดในนามของผู้ใช้

เมื่อมีข้อมูลเข้าสู่ระบบเหล่านี้แล้ว ให้เพิ่มข้อมูลต่อไปนี้ลงในไฟล์ ads.properties

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE

ดูข้อมูลเพิ่มเติมได้ที่คู่มือเวิร์กโฟลว์การตรวจสอบสิทธิ์ผู้ใช้รายเดียว

ขั้นตอนการตรวจสอบสิทธิ์ผู้ใช้หลายคนหนึ่งเครื่อง

เราขอแนะนำให้ใช้เวิร์กโฟลว์นี้หากแอปของคุณอนุญาตให้ผู้ใช้ลงชื่อเข้าใช้และให้สิทธิ์แอปจัดการบัญชี Google Ads ในนามของผู้ใช้ ตัวอย่างโค้ด GenerateUserCredentials เป็นเครื่องมือบรรทัดคำสั่งที่แสดงวิธีรับการตรวจสอบสิทธิ์ผู้ใช้ที่รันไทม์เพื่อจัดการบัญชี Google Ads ในนามของผู้ใช้ คุณสามารถใช้ตัวอย่างโค้ดนี้เป็นข้อมูลอ้างอิงเพื่อสร้างแอปบนเดสก์ท็อปหรือเว็บแอปที่ต้องมีการตรวจสอบสิทธิ์ผู้ใช้

สำหรับแอปพลิเคชันที่มีผู้ใช้หลายคนหนึ่งเครื่อง ให้จัดเก็บรหัสไคลเอ็นต์ OAuth 2.0 และรหัสลับไคลเอ็นต์ของแอปพลิเคชันไว้ใน ads.properties (หรือที่เก็บการกำหนดค่าอื่น) ขณะที่จัดเก็บโทเค็นการรีเฟรชของผู้ใช้ปลายทางแต่ละรายไว้อย่างปลอดภัยในฐานข้อมูลแอปพลิเคชัน และส่งผ่านโดยใช้โปรแกรมขณะรันไทม์เมื่อสร้าง UserCredentials และ GoogleAdsClient ดังนี้

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

ดูข้อมูลเพิ่มเติมได้ที่คู่มือเวิร์กโฟลว์การตรวจสอบสิทธิ์แบบหลายคนหนึ่งเครื่อง

จัดการบัญชีหลายบัญชี

เป็นเรื่องปกติที่ผู้ใช้จะจัดการบัญชี Google Ads มากกว่า 1 บัญชี ไม่ว่าจะผ่านการเข้าถึงบัญชีโดยตรงหรือผ่านบัญชีดูแลจัดการ Google Ads ไลบรารีของไคลเอ็นต์ Java มีตัวอย่างโค้ดต่อไปนี้ซึ่งแสดงวิธีจัดการกับกรณีดังกล่าว

  1. ตัวอย่างโค้ด GetAccountHierarchy แสดงวิธีดึงข้อมูลรายการบัญชีทั้งหมดภายใต้บัญชีดูแลจัดการ Google Ads
  2. ตัวอย่างโค้ด ListAccessibleCustomers แสดงวิธีดึงข้อมูลรายการบัญชีทั้งหมดที่ผู้ใช้มีสิทธิ์เข้าถึงโดยตรง จากนั้นจะใช้บัญชีเหล่านี้เป็นค่าที่ถูกต้องสำหรับการตั้งค่า loginCustomerId ได้

ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน

ไลบรารีของไคลเอ็นต์ Java ยังรองรับการตรวจสอบสิทธิ์ด้วยข้อมูลรับรองเริ่มต้นของแอปพลิเคชันด้วย

ซึ่งจะเป็นประโยชน์อย่างยิ่งสำหรับการพัฒนาในเครื่องหรือการพัฒนาสำหรับ Google APIs ต่างๆ เนื่องจากคุณสามารถใช้ข้อมูลเข้าสู่ระบบเดียวกันซ้ำได้ หากข้อมูลเข้าสู่ระบบดังกล่าวเข้าถึงขอบเขต OAuth 2.0 ที่จำเป็นได้

สำหรับ Google Ads API โปรดตรวจสอบว่าข้อมูลรับรองเริ่มต้นของแอปพลิเคชันสามารถเข้าถึงขอบเขต OAuth 2.0 https://www.googleapis.com/auth/adwords ได้

หากต้องการใช้ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน ให้ตั้งค่าตัวเลือก api.googleads.useApplicationDefaultCredentials เป็น true ในไฟล์ ads.properties (หรือเรียกใช้ .enableApplicationDefaultCredentials() ใน GoogleAdsClient.newBuilder()) เมื่อใช้ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน คุณไม่ควรตั้งค่ารหัสไคลเอ็นต์ รหัสลับไคลเอ็นต์ และโทเค็นการรีเฟรช