ตัวอย่าง

คู่มือนี้มีตัวอย่างการเรียกปลายทาง 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