เริ่มต้นใช้งาน

เราขอแนะนำให้ใช้ไลบรารีของไคลเอ็นต์กับ Apache Maven หรือ Gradle

สร้างโปรเจ็กต์ Maven/Gradle ใหม่

สร้างโปรเจ็กต์ Maven หรือ Gradle ใหม่ใน IDE ที่คุณเลือก อาร์ติแฟกต์ของเรา เผยแพร่ในที่เก็บส่วนกลางของ Maven

เราขอแนะนำให้ใช้รายการวัสดุ (BOM) ของ Google Ads API เพื่อจัดการเวอร์ชันการอ้างอิง วิธีนี้เป็นวิธีที่ดีที่สุดในการหลีกเลี่ยงความขัดแย้งด้านการอ้างอิงกับไลบรารี เช่น Guava และ GAX ซึ่งเฟรมเวิร์กอื่นๆ ก็ใช้เช่นกัน BOM ช่วยให้มั่นใจได้ว่าคุณใช้การขึ้นต่อกันเหล่านี้ในเวอร์ชันที่แน่นอน ซึ่งได้รับการทดสอบกับไลบรารีไคลเอ็นต์ของ Google Ads แล้ว

ทรัพยากร Dependency ของ Maven คือ

<!-- Import the Bill of Materials (BOM) to ensure you're using compatible
     versions of all google-ads libraries. -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>google-ads-bom</artifactId>
      <version>40.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<!-- Add the google-ads dependency, without a version. The version is
     managed by the BOM. -->
<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
</dependency>

Dependency ของ Gradle คือ

// Import the Bill of Materials (BOM).
implementation platform('com.google.api-ads:google-ads-bom:40.0.0')

// Add the google-ads dependency, without a version.
implementation 'com.google.api-ads:google-ads'

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

หากคุณสร้างจากแหล่งที่มา โปรดตรวจสอบว่าได้เปิดใช้การประมวลผลคำอธิบายประกอบใน IDE

การประกาศทรัพยากร Dependency ที่ครอบคลุมโดย BOM

BOM ของ Google Ads API มีการจัดการเวอร์ชันสำหรับไลบรารีทั่วไปหลายรายการ เช่น Guava, Protobuf, GAX และ gRPC คุณต้องไม่ระบุเวอร์ชันเมื่อประกาศการอ้างอิงที่ BOM ครอบคลุมเพื่อหลีกเลี่ยงความขัดแย้งของการอ้างอิงที่อาจเกิดขึ้น BOM จะจัดการเวอร์ชันของไลบรารีเหล่านี้โดยอัตโนมัติเพื่อให้มั่นใจถึง ความเข้ากันได้

เช่น หากต้องการประกาศทรัพยากร Dependency Guava ใน Maven ให้ใช้โค้ดต่อไปนี้

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <!-- NO VERSION SPECIFIED -->
</dependency>

และใน Gradle ให้ทำดังนี้

implementation 'com.google.guava:guava' // NO VERSION SPECIFIED

การละเว้นเวอร์ชันจะช่วยให้ BOM จัดการเวอร์ชันได้ ซึ่งจะช่วยป้องกันปัญหา ที่เกิดจากเวอร์ชันการอ้างอิงที่ไม่เข้ากัน ตัวบ่งชี้ที่พบบ่อยของความขัดแย้งด้านการอ้างอิง ได้แก่ NoSuchMethodError หรือ ClassNotFoundException ซึ่งมักแก้ไขได้โดยตรวจสอบว่าการอ้างอิงทั้งหมดที่จัดการโดย BOM ไม่ได้ระบุเวอร์ชัน

รับข้อมูลเข้าสู่ระบบเพื่อตรวจสอบสิทธิ์ด้วย API

การเข้าถึง Google Ads API ต้องใช้ข้อมูลเข้าสู่ระบบ OAuth และโทเค็นของนักพัฒนา Google Ads API ส่วนนี้จะอธิบายว่าสิ่งเหล่านี้คืออะไร วิธีการใช้งาน และวิธีรับ

โทเค็นของนักพัฒนา (สำหรับการเข้าถึง API)

โทเค็นของนักพัฒนาซอฟต์แวร์ลิงก์กับบัญชีดูแลจัดการและดูได้ในอินเทอร์เฟซเว็บของ Google Ads

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

ข้อมูลเข้าสู่ระบบ OAuth (สําหรับการเข้าถึงบัญชี Google Ads)

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

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

หากคุณให้สิทธิ์โดยใช้ข้อมูลเข้าสู่ระบบของคุณเอง (ขั้นตอนของแอปบนเดสก์ท็อป)

ดูโฟลว์แอปเดสก์ท็อป OAuth ซึ่งรวมถึงรายละเอียดทั้งหมดที่คุณ ต้องใช้ในการให้สิทธิ์ด้วยข้อมูลเข้าสู่ระบบของคุณเอง

หากคุณให้สิทธิ์ในฐานะผู้ใช้ Google บุคคลที่สาม (ขั้นตอนบนเว็บ)

ดูขั้นตอนของเว็บแอป OAuth ซึ่ง แสดงตัวอย่างวิธีตั้งค่าการให้สิทธิ์ OAuth สำหรับผู้ใช้บุคคลที่สาม ที่ไม่เจาะจง

หากคุณให้สิทธิ์ในฐานะผู้ใช้โดเมน Google Apps (ขั้นตอนบัญชีบริการ)

ดูโฟลว์บัญชีบริการ OAuth ซึ่งแสดงตัวอย่างวิธี ตั้งค่าการให้สิทธิ์ OAuth สำหรับผู้ใช้โดเมน Google Apps

หากสิทธิ์เข้าถึงบัญชีลูกค้า Google Ads ของคุณมาจากบัญชีดูแลจัดการ Google Ads คุณต้องระบุรหัสลูกค้าสำหรับการเข้าสู่ระบบด้วยตามที่อธิบายไว้ด้านล่าง

รหัสลูกค้าสำหรับเข้าสู่ระบบ (สําหรับการเข้าถึงบัญชี Google Ads ผ่านบัญชีดูแลจัดการ)

หมายเหตุ: ผู้ใช้ Google สามารถมีสิทธิ์เข้าถึงบัญชี Google Ads หลายบัญชี

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

กำหนดค่าไลบรารีของไคลเอ็นต์ด้วยข้อมูลเข้าสู่ระบบ

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

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

สร้างไฟล์ ~/ads.properties ที่มีเนื้อหาต่อไปนี้

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

แทนที่ตัวยึดตำแหน่งด้วยข้อมูลเข้าสู่ระบบที่คุณได้รับในขั้นตอนก่อนหน้า

นอกจากนี้ หากโทเค็นการรีเฟรชเป็นของบัญชีดูแลจัดการ คุณควร ระบุรหัสลูกค้าของบัญชีนี้เป็นลูกค้าระบบการเข้าสู่ระบบ

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

ตรวจสอบความถูกต้องของข้อมูลเข้าสู่ระบบ

เราจะเรียกใช้GetCampaigns example เพื่อให้แน่ใจว่าทุกอย่างได้รับการตั้งค่าอย่างถูกต้อง

ก่อนอื่น ให้ไปที่ไดเรกทอรี google-ads-examples

cd google-ads-examples

ตัวอย่างนี้ต้องมี--customerIdพารามิเตอร์ที่มีค่าเป็นรหัสลูกค้าบัญชี Google Ads ของคุณโดยไม่มีขีดกลาง

หากต้องการเรียกใช้ด้วย Gradle ให้ทำดังนี้

./gradlew -q runExample --example="basicoperations.GetCampaigns --customerId INSERT_CUSTOMER_ID_HERE"

ดูตัวอย่างอื่นๆ

แพ็กเกจ examples ใน google-ads-examples มีตัวอย่างที่มีประโยชน์หลายอย่าง ตัวอย่างส่วนใหญ่ต้องใช้ พารามิเตอร์ คุณจะส่งพารามิเตอร์เป็นอาร์กิวเมนต์ (แนะนํา) หรือ แก้ไขค่า INSERT_XXXXX_HERE ในซอร์สโค้ดก็ได้ หากต้องการดูคำสั่งการใช้งาน สำหรับตัวอย่าง ให้ส่ง --help เป็นอาร์กิวเมนต์เดียว

ด้วย Gradle

./gradlew -q runExample --example="basicoperations.GetCampaigns --help"

นอกจากนี้ คุณยังใช้listExamplesใน Gradle เพื่อแสดงตัวอย่างทั้งหมด ตัวอย่างในไดเรกทอรีย่อย หรือตัวอย่างที่คำอธิบายมีคำค้นหาได้ด้วย

# List all examples:
./gradlew -q listExamples
# List examples in the 'basicoperations' subdirectory:
./gradlew -q listExamples --subdirectory='basicoperations'
# Search for examples where the description includes 'Performance Max':
./gradlew -q listExamples --searchTerm='Performance Max'

หมายเหตุ: จากซอร์สโค้ด คุณสามารถละเว้นความคิดเห็นที่มี [START...] และ [END...] ได้ เนื่องจาก Google ใช้ความคิดเห็นเหล่านี้โดยเฉพาะ