คู่มือนี้มีตัวอย่างการเรียกใช้ปลายทาง REST โดยตรงโดยไม่ใช้ไลบรารีของไคลเอ็นต์
สิ่งที่ต้องดำเนินการก่อน
ตัวอย่างทั้งหมดด้านล่างนี้มีไว้เพื่อคัดลอกและวางลงใน Bash Shell โดยใช้คำสั่ง curl
นอกจากนี้ คุณจะต้องมีโทเค็นของนักพัฒนาซอฟต์แวร์ สิทธิ์การเข้าถึงบัญชีทดสอบก็ใช้ได้ และบัญชีดูแลจัดการ Google Ads ที่มีบัญชีลูกค้าอย่างน้อย 1 บัญชี
ตัวแปรสภาพแวดล้อม
ป้อนข้อมูลเข้าสู่ระบบของบัญชีและรหัสด้านล่าง แล้วคัดลอกและวางลงในเทอร์มินัลเพื่อกำหนดค่าตัวแปรสภาพแวดล้อมที่ใช้ในตัวอย่างต่อๆ ไป คู่มือการให้สิทธิ์จะบอกวิธีการสร้างโทเค็นเพื่อการเข้าถึง 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
มิเช่นนั้น ตัวเลือก Mutates - สร้างตัวอย่าง 2 รายการจะสร้างงบประมาณและแคมเปญใหม่
ค้นหา
คู่มือตำราอาหารคำค้นหามีตัวอย่างการรายงานจำนวนมากที่สอดคล้องกับหน้าจอเริ่มต้นของ Google Ads บางส่วนและใช้งานได้กับตัวแปรสภาพแวดล้อมเดียวกันกับที่ใช้ในคู่มือนี้ เครื่องมือสร้างข้อความค้นหาแบบโต้ตอบของเรายังเป็นแหล่งข้อมูลที่ดีในการสร้างการค้นหาที่กำหนดเองแบบอินเทอร์แอกทีฟ
แบ่งหน้าแล้ว
เมธอด 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
สร้าง
ตัวอย่างนี้สร้างงบประมาณแคมเปญที่ใช้ร่วมกัน 2 รายการในคำขอเดียว
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
การดำเนินการทั้งหมดในคำขอจะสำเร็จต่อเมื่อทุกอย่างถูกต้อง
ตัวอย่างถัดไปใช้แคมเปญที่มีอยู่ คุณคัดลอกและวางได้จากเอาต์พุตตัวอย่าง Creates
CAMPAIGN_ID=CAMPAIGN_ID
คำขอต่อไปนี้มีการดำเนินการ 2 อย่าง แคมเปญแรกพยายามเปลี่ยนกลยุทธ์การเสนอราคาของแคมเปญที่ระบุ และครั้งถัดไปพยายามนำแคมเปญที่มีรหัสไม่ถูกต้องออก เนื่องจากการดำเนินการที่ 2 ทำให้เกิดข้อผิดพลาด (รหัสแคมเปญไม่ถูกต้อง) และเนื่องจากตั้งค่า 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' } ] }"
การดำเนินการที่จัดกลุ่ม
เมธอด googleAds:mutate
รองรับการส่งกลุ่มการดำเนินการด้วยทรัพยากรหลายประเภท คุณส่งการดำเนินการประเภทต่างๆ มากมายเพื่อเชื่อมโยงลำดับการดำเนินการที่ควรดำเนินการเป็นกลุ่มได้
ชุดการดำเนินการจะสำเร็จหากไม่มีการดำเนินการใดล้มเหลวหรือล้มเหลวทั้งหมดหากการดำเนินการเดียวล้มเหลว
ตัวอย่างนี้แสดงให้เห็นถึงการสร้างงบประมาณแคมเปญ แคมเปญ กลุ่มโฆษณา และโฆษณารวมกันเป็นชุดการทำงานเดียว การดำเนินการติดต่อกันแต่ละครั้ง จะต้องอาศัยการดำเนินการก่อนหน้านี้ หากไม่สำเร็จ การดำเนินการทั้งกลุ่มจะล้มเหลว
ระบบจะใช้จำนวนเต็มลบ (-1
, -2
, -3
) เป็นตัวยึดตำแหน่งในชื่อทรัพยากรและจะเติมแบบไดนามิกขณะรันไทม์ด้วยผลลัพธ์จากลำดับการดำเนินการ
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
แบบง่ายไปยังเมธอด 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}" \
การอัปโหลดชิ้นงานไบนารี
เมธอด assets:mutate
ใช้สำหรับการอัปโหลดและจัดการชิ้นงาน ระบบจะเข้ารหัสข้อมูลไบนารี เช่น รูปภาพ
เป็นสตริงโดยใช้การเข้ารหัส base64 แบบมาตรฐานพร้อมระยะห่างจากขอบ ยอมรับการเข้ารหัส base64 แบบใช้ URL แบบมาตรฐานหรือแบบใช้ URL แบบมีหรือไม่มีระยะห่างจากขอบ
ตัวอย่างนี้เข้ารหัส GIF ขนาด 1 พิกเซลเพื่อให้ตัวอย่างมีความกระชับ ในทางปฏิบัติ เพย์โหลด data
จะมีขนาดใหญ่กว่ามาก
ใช้ยูทิลิตีบรรทัดคำสั่ง base64
(ส่วนหนึ่งของ GNU Core Core) เพื่อเข้ารหัสรูปภาพ GIF ขนาด 1 พิกเซล
base64 1pixel.gif
ค่าที่เข้ารหัสฐาน 64 จะระบุเป็นแอตทริบิวต์ 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' } } } ] }"