คู่มือนี้มีตัวอย่างการเรียกปลายทาง REST โดยตรงโดยไม่ต้องใช้ไลบรารีของไคลเอ็นต์
สคริปต์ในคู่มือนี้อยู่ในที่เก็บ GitHub ของตัวอย่างโค้ด REST รวมถึงไดเรกทอรี rest_guide
หากต้องการดูเนื้อหาคำขอและการตอบกลับสำหรับเมธอด API แต่ละรายการ โปรดดูเอกสารอ้างอิงสำหรับปลายทางบริการที่เฉพาะเจาะจง
ตัวอย่างเช่น หน้าอ้างอิงสำหรับ GoogleAdsService.Search จะแสดงเนื้อหาคำขอและการตอบกลับสำหรับเมธอด Search
ข้อกำหนดเบื้องต้น
ตัวอย่างทั้งหมดที่แสดงที่นี่มีไว้เพื่อคัดลอกและวางลงใน bash shell โดยใช้คำสั่ง curl
นอกจากนี้ คุณยังต้องมีโปรเจ็กต์ Google Cloud (ใช้สิทธิ์เข้าถึงบัญชีทดสอบได้) และบัญชีดูแลจัดการ Google Ads ที่มีบัญชีลูกค้าอย่างน้อย 1 บัญชี
ตัวแปรสภาพแวดล้อม
ป้อนข้อมูลเข้าสู่ระบบของบัญชีและรหัสตามที่แสดง จากนั้นคัดลอกและวางลงในเทอร์มินัลเพื่อกำหนดค่าตัวแปรสภาพแวดล้อมที่ใช้ในตัวอย่างต่อๆ ไป คู่มือการให้สิทธิ์จะแสดงวิธีการสร้างโทเค็นเพื่อการเข้าถึง OAuth 2.0
API_VERSION="26"
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 - Creates examples ทั้ง 2 รายการจะสร้างงบประมาณและแคมเปญใหม่
ค้นหา
คู่มือ Query Cookbook มีตัวอย่างการรายงานจำนวนมากที่สอดคล้องกับหน้าจอ Google Ads เริ่มต้นบางหน้าจอ และทำงานร่วมกับตัวแปรสภาพแวดล้อมเดียวกันกับที่ใช้ในคู่มือนี้ เครื่องมือสร้างการค้นหาแบบอินเทอร์แอกทีฟของเรายังเป็นแหล่งข้อมูลที่ยอดเยี่ยมสำหรับการสร้างการค้นหาที่กำหนดเองแบบอินเทอร์แอกทีฟด้วย
แบ่งหน้า
เมธอด search ใช้การแบ่งหน้า โดยมีขนาดหน้าคงที่ 10,000 รายการและมีการระบุ page_token ควบคู่ไปกับ query
สำหรับคำขอแรก ให้เว้น PAGE_TOKEN ว่างไว้ หากต้องการดูหน้าถัดไป ให้ตั้งค่า PAGE_TOKEN เป็นค่า nextPageToken จากการตอบกลับก่อนหน้า แล้วเรียกใช้คำขออีกครั้ง
PAGE_TOKEN=""curl
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "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}" } EOF
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 --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<'EOF' { "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' " } EOF
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 --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "create": { "name": "My Campaign Budget #${RANDOM}", "amountMicros": 500000 } }, { "create": { "name": "My Campaign Budget #${RANDOM}", "amountMicros": 500000 } } ] } EOF
ตัวอย่างถัดไปใช้ BUDGET_ID ของงบประมาณแคมเปญที่มีอยู่ คุณสามารถคัดลอกและวางจากเอาต์พุตของขั้นตอนก่อนหน้าได้
BUDGET_ID=BUDGET_IDทรัพยากรที่อ้างอิงถึงทรัพยากรอื่นๆ จะอ้างอิงตามชื่อทรัพยากร
แคมเปญที่สร้างในตัวอย่างต่อไปนี้อ้างอิงถึง campaignBudget ตามชื่อทรัพยากรที่มีค่าเป็นสตริง
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "create": { "status": "PAUSED", "advertisingChannelType": "SEARCH", "geoTargetTypeSetting": { "positiveGeoTargetType": "PRESENCE_OR_INTEREST", "negativeGeoTargetType": "PRESENCE" }, "name": "My Search campaign #${RANDOM}", "campaignBudget": "customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}", "targetSpend": {}, "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING" } } ] } EOF
อัปเดต
อัปเดตแอตทริบิวต์ของออบเจ็กต์ที่มีอยู่โดยใช้การดำเนินการ update รายการ ตัวอย่างถัดไปใช้แคมเปญที่มีอยู่ คุณสามารถคัดลอกและวางจากเอาต์พุตของขั้นตอนก่อนหน้าได้
CAMPAIGN_ID=CAMPAIGN_IDการอัปเดตทั้งหมดต้องมีช่อง updateMask ซึ่งเป็นรายการที่คั่นด้วยคอมมาของแอตทริบิวต์ JSON ที่ควรอยู่ในคำขอ ซึ่งควรใช้เป็นการอัปเดต
แอตทริบิวต์ที่แสดงใน updateMask แต่ไม่ปรากฏในเนื้อหาคำขอจะถูกล้างในออบเจ็กต์ ระบบจะไม่สนใจแอตทริบิวต์ที่ไม่ได้ระบุใน updateMask แต่มีอยู่ในเนื้อหาคำขอ
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "update": { "resourceName": "customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}", "name": "A changed campaign name #${RANDOM}" }, "updateMask": "name" } ] } EOF
นำออก
ระบบจะนำออบเจ็กต์ออกโดยระบุชื่อทรัพยากรเป็นการดำเนินการ remove
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "remove": "customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}" } ] } EOF
ไม่สำเร็จบางส่วน
เมื่อมีการดำเนินการหลายรายการในคำขอเดียว ให้ระบุ partialFailure (ไม่บังคับ) หากเป็น true ระบบจะดำเนินการที่ถูกต้องและแสดงข้อผิดพลาดสำหรับการดำเนินการที่ไม่ถูกต้อง หากเป็น false การดำเนินการทั้งหมดในคำขอจะสำเร็จก็ต่อเมื่อการดำเนินการทั้งหมดถูกต้องเท่านั้น
ตัวอย่างถัดไปใช้แคมเปญที่มีอยู่ คุณสามารถคัดลอกและวางจากเอาต์พุตตัวอย่าง Creates ได้
CAMPAIGN_ID=CAMPAIGN_IDคำขอต่อไปนี้มีการดำเนินการ 2 รายการ โดยรายการแรกจะปิดใช้ CPC ที่ปรับปรุงแล้วในแคมเปญที่ระบุ และรายการที่ 2 จะพยายามนำแคมเปญที่มีรหัสไม่ถูกต้องออก เนื่องจากช่อง partialFailure ตั้งค่าเป็น true การดำเนินการแรกจึงสำเร็จ ขณะที่การตอบกลับแสดงข้อผิดพลาดสำหรับการดำเนินการที่ 2 ที่ไม่ถูกต้องในช่อง partialFailureError
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "partialFailure": true, "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" } ] } EOF
การดำเนินการที่จัดกลุ่ม
เมธอด googleAds:mutate รองรับการส่งกลุ่มการดำเนินการที่มีทรัพยากรหลายประเภท คุณสามารถส่งการดำเนินการหลายประเภทเพื่อเชื่อมโยงลำดับการดำเนินการที่ควรดำเนินการเป็นกลุ่มเข้าด้วยกัน
ชุดการดำเนินการจะสำเร็จหากไม่มีการดำเนินการใดล้มเหลว หรือจะล้มเหลวทั้งหมดหากมีการดำเนินการใดๆ ล้มเหลว
ตัวอย่างนี้แสดงการสร้างงบประมาณแคมเปญ แคมเปญ กลุ่มโฆษณา และโฆษณาพร้อมกันเป็นชุดการดำเนินการเดียว การดำเนินการที่ต่อเนื่องกันแต่ละรายการจะขึ้นอยู่กับการดำเนินการก่อนหน้า หากการดำเนินการรายการใดรายการหนึ่งล้มเหลว การดำเนินการทั้งกลุ่มจะล้มเหลว
จำนวนเต็มลบ (-1, -2, -3) จะใช้เป็นตัวยึดตำแหน่งในชื่อทรัพยากร และจะมีการป้อนข้อมูลแบบไดนามิกที่รันไทม์ด้วยผลลัพธ์จากลำดับการดำเนินการ
curl --compressed --fail-with-body --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "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" }, "name": "My Search campaign #${RANDOM}", "campaignBudget": "customers/${CUSTOMER_ID}/campaignBudgets/-1", "targetSpend": {}, "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING" } } }, { "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": [ { "pinnedField": "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" ] } } } } ] } EOF
การจัดการบัญชี
คุณสามารถสร้างบัญชี แสดงรายการบัญชีที่เข้าถึงได้ และอัปโหลดชิ้นงานไบนารี
สร้างบัญชี
สร้างบัญชีใหม่โดยใช้เมธอด createCustomerClient โปรดทราบว่า URL ต้องใช้รหัสบัญชีดูแลจัดการแทนรหัสบัญชีลูกค้า ระบบจะสร้างบัญชีลูกค้าใหม่ภายใต้บัญชีดูแลจัดการ
curl -f --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "customerClient": { "descriptiveName": "Account created with CustomerService #${RANDOM}", "currencyCode": "USD", "timeZone": "America/New_York" } } EOF
แสดงรายการบัญชีที่เข้าถึงได้
ใช้คำขอ 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 "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}"
อัปโหลดชิ้นงานไบนารี
ใช้เมธอด assets:mutate เพื่ออัปโหลดและจัดการชิ้นงาน เข้ารหัสข้อมูลไบนารี เช่น รูปภาพ เป็นสตริง Base64 API ยอมรับการเข้ารหัส Base64 มาตรฐานหรือ URL-safe โดยมีหรือไม่มีการเติมอักขระก็ได้
ตัวอย่างนี้จะเข้ารหัสรูปภาพ GIF ขนาด 1 พิกเซลเพื่อรักษาเพย์โหลดให้กระชับ ในทางปฏิบัติ เพย์โหลด data จะมีขนาดใหญ่กว่ามาก ดาวน์โหลดรูปภาพและใช้ยูทิลิตีบรรทัดคำสั่ง base64 เพื่อเข้ารหัสรูปภาพ
curl -sLO https://developers.google.com/google-ads/api/images/1pixel.gif
IMAGE_CONTENT="$(base64 < 1pixel.gif | tr -d '[:space:]')"ส่งค่าที่เข้ารหัส base64 ในช่อง data ของคำขอ assets:mutate ดังนี้
curl -f --request POST \ "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \ --header "Content-Type: application/json" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data @- <<EOF { "operations": [ { "create": { "imageAsset": { "data": "${IMAGE_CONTENT}" }, "name": "Marketing Image" } } ] } EOF