Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

ตัวอย่าง

คู่มือนี้มีตัวอย่างการเรียกใช้ปลายทาง REST โดยตรงโดยไม่ต้องใช้ไลบรารีของไคลเอ็นต์

ดูตัวอย่างโค้ดโดยละเอียดเพิ่มเติมได้ที่ที่เก็บ GitHub ของตัวอย่างโค้ด REST GitHub repository.

หากต้องการดูเนื้อหาของคำขอและการตอบกลับสำหรับเมธอด API แต่ละรายการ โปรดดูเอกสารอ้างอิงสำหรับปลายทางบริการที่เฉพาะเจาะจง

ตัวอย่างเช่น หน้าอ้างอิง สำหรับ GoogleAdsService.Search จะแสดงเนื้อหาของคำขอและการตอบกลับสำหรับเมธอด Search

ข้อกำหนดเบื้องต้น

ตัวอย่างทั้งหมดที่แสดงที่นี่มีไว้เพื่อคัดลอกและวางลงใน bash shell โดยใช้คำสั่ง curl

นอกจากนี้ คุณยังต้องมีโทเค็นของนักพัฒนาแอป สิทธิ์เข้าถึง บัญชีทดสอบ และบัญชีดูแลจัดการ Google Ads ที่มีบัญชีลูกค้าอย่างน้อย 1 บัญชี

สำคัญ: ในตัวอย่างเหล่านี้ เราจะถือว่าคุณเข้าถึงบัญชีลูกค้า (CUSTOMER_ID) โดยผู้ใช้ที่มีสิทธิ์เข้าถึงระดับผู้ดูแลระบบในบัญชีดูแลจัดการ (MANAGER_CUSTOMER_ID) ซึ่งจัดการบัญชีลูกค้าโดยตรง หากคุณเข้าถึงบัญชีลูกค้าแต่ละบัญชีโดยตรง ให้ละเว้นส่วนหัว login-customer-id หรือตั้งค่าให้มีค่าเดียวกับ CUSTOMER_ID โปรดทราบ ว่าตัวอย่างบางรายการ เช่น การสร้างบัญชี ต้องใช้บัญชีดูแลจัดการ

ตัวแปรสภาพแวดล้อม

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

API_VERSION="25"
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 - Creates 2 รายการจะสร้างงบประมาณ และแคมเปญใหม่

ค้นหา

คู่มือ Query Cookbook มีตัวอย่างการรายงาน มากมายที่สอดคล้องกับหน้าจอ 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'

Mutates

คุณสามารถส่งการดำเนินการ mutate หลายรายการ (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 operation

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 มาตรฐานพร้อมการเพิ่ม Padding ระบบยอมรับการเข้ารหัส Base64 มาตรฐานหรือ URL-safe โดยมีหรือไม่มีการเพิ่ม Padding

ตัวอย่างนี้เข้ารหัส GIF ขนาด 1 พิกเซลเพื่อให้ตัวอย่างกระชับ ในทางปฏิบัติ เพย์โหลด data จะมีขนาดใหญ่กว่ามาก

ใช้ยูทิลิตีบรรทัดคำสั่ง base64 (ส่วนหนึ่งของ ยูทิลิตีหลักของ GNU) เพื่อเข้ารหัสรูปภาพ GIF ขนาด 1 พิกเซล

base64 1pixel.gif

ระบบจะระบุค่าที่เข้ารหัส Base64 เป็นแอตทริบิวต์ 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'
      }
    }
  }
]
}"

ข้อผิดพลาดที่พบบ่อย

ลองใช้เลย

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

ข้อกำหนดเบื้องต้น

ตัวแปรสภาพแวดล้อม

รหัสออบเจ็กต์เพิ่มเติมที่ไม่บังคับ

ค้นหา

แบ่งหน้า

curl

GAQL

สตรีมมิง

curl

GAQL

Mutates

สร้าง

อัปเดต

นำออก

ไม่สำเร็จบางส่วน

การดำเนินการแบบจัดกลุ่ม

การจัดการบัญชี

สร้างบัญชี

แสดงรายการบัญชีที่เข้าถึงได้

อัปโหลดเนื้อหาไบนารี

ตัวอย่าง