คู่มือนี้มีตัวอย่างการเรียกใช้ปลายทาง REST โดยตรงโดยไม่ใช้ไลบรารีของไคลเอ็นต์
ข้อกำหนดเบื้องต้น
ตัวอย่างทั้งหมดด้านล่างนี้มีไว้เพื่อคัดลอกและวางลงใน bash Shell โดยใช้คำสั่ง curl
นอกจากนี้ คุณต้องมีโทเค็นของนักพัฒนาซอฟต์แวร์ สิทธิ์เข้าถึงบัญชีทดสอบก็ไม่เป็นไร และบัญชีดูแลจัดการ Google Ads ที่มีบัญชีลูกค้าอย่างน้อย 1 บัญชี
ตัวแปรสภาพแวดล้อม
ป้อนข้อมูลประจำตัวและรหัสบัญชีด้านล่าง จากนั้นคัดลอกและวางลงในเทอร์มินัลเพื่อกำหนดค่าตัวแปรสภาพแวดล้อมที่ใช้ในตัวอย่างถัดไป คำแนะนำการให้สิทธิ์จะแสดงวิธีการสร้างโทเค็นเพื่อการเข้าถึง OAuth 2.0
API_VERSION="16"
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
ไม่เช่นนั้น ให้ตั้งปุ่มปรับ - สร้างตัวอย่าง 2 รายการเพื่อสร้างงบประมาณและแคมเปญใหม่
ค้นหา
คู่มือตำราอาหารในการค้นหามีตัวอย่างการรายงานจำนวนมากที่สอดคล้องกับหน้าจอเริ่มต้นของ Google Ads บางส่วน และทำงานกับตัวแปรสภาพแวดล้อมเดียวกันกับที่ใช้ในคู่มือนี้ นอกจากนี้ เครื่องมือสร้างคำค้นหาแบบอินเทอร์แอกทีฟของเรายังเป็นแหล่งข้อมูลที่ยอดเยี่ยมในการสร้างคำค้นหาที่กำหนดเองแบบอินเทอร์แอกทีฟ
แบ่งหน้าแล้ว
เมธอด search
ใช้การแบ่งหน้า โดยมีพารามิเตอร์ pageSize
ที่ปรับแต่งได้ซึ่งระบุไว้ข้าง 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 '{ "pageSize": 10, "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'
สตรีมมิง
เมธอด 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
การดำเนินการทั้งหมดในคำขอจะสำเร็จก็ต่อเมื่อถูกต้องทั้งหมด
ตัวอย่างถัดไปใช้แคมเปญที่มีอยู่ ซึ่งคุณสามารถคัดลอกและวางจากเอาต์พุตสร้างตัวอย่างได้
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 ทั้งแบบที่มีหรือไม่มีระยะห่างจากขอบ
ตัวอย่างนี้เข้ารหัส GIF ขนาด 1 พิกเซลเพื่อให้ตัวอย่างกระชับยิ่งขึ้น ในทางปฏิบัติ เพย์โหลด data
จะมีขนาดใหญ่กว่ามาก
ใช้ยูทิลิตีบรรทัดคำสั่ง base64
(เป็นส่วนหนึ่งของยูทิลิตีหลักของ GNU) เพื่อเข้ารหัสรูปภาพ 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' } } } ] }"