Chú ý: Bạn đang xem tài liệu về giao diện REST của API. Hầu hết các thư viện ứng dụng chính thức của chúng tôi đều sử dụng gRPC. Hãy xem Giới thiệu về REST để biết chi tiết.

Trang này được dịch bởi Cloud Translation API.

Ví dụ

Hướng dẫn này cung cấp các ví dụ về cách gọi trực tiếp điểm cuối REST mà không cần sử dụng thư viện ứng dụng.

Điều kiện tiên quyết

Tất cả các mẫu dưới đây được sao chép và dán vào dấu gạch ngang shell bằng lệnh curl.

Bạn cũng cần mã của nhà phát triển, mã kiểm thử quyền truy cập vào tài khoản là bình thường và Tài khoản người quản lý Google Ads có ít nhất một tài khoản khách hàng.

Biến môi trường

Nhập thông tin đăng nhập và mã tài khoản bên dưới, sau đó sao chép và dán vào Terminal để định cấu hình các biến môi trường được sử dụng trong các ví dụ tiếp theo. Hướng dẫn Uỷ quyền cung cấp hướng dẫn cách tạo một Mã truy cập 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"

Mã đối tượng không bắt buộc khác

Một số ví dụ sau đây áp dụng với ngân sách hoặc chiến dịch có sẵn. Nếu bạn có ID của các đối tượng hiện có để sử dụng với các ví dụ này, hãy nhập chúng vào bên dưới.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Nếu không, hai ví dụ về Mutates - Creates (Tạo đối tượng khách hàng) sẽ tạo ngân sách mới và chiến dịch.

Tìm kiếm

Hướng dẫn về Hướng dẫn về truy vấn chứa nhiều báo cáo các mẫu tương ứng với một số màn hình mặc định của Google Ads và tương thích với các biến môi trường tương tự được dùng trong hướng dẫn này. Truy vấn tương tác của chúng tôi công cụ tạo của bạn là cũng là một tài nguyên hữu ích để xây dựng các truy vấn tuỳ chỉnh theo tính tương tác.

Được phân trang

Phương thức search sử dụng tính năng phân trang, với kích thước trang cố định là 10.000 mục và page_token được chỉ định cùng với 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}"
}'

Google Analytics 4 (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'

Phát trực tiếp

Phương thức searchStream truyền trực tuyến tất cả kết quả trong một phản hồi duy nhất, do đó, Trường pageSize không được hỗ trợ.

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'
"
}'

Google Analytics 4 (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'

Thay đổi

Có thể gửi nhiều thao tác thay đổi (create, update hoặc remove) trong một nội dung yêu cầu JSON duy nhất bằng cách điền mảng operations.

Sáng tạo

Ví dụ này tạo hai ngân sách chiến dịch dùng chung trong một yêu cầu duy nhất.

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,
    }
  }
]
}"

Ví dụ tiếp theo sử dụng BUDGET_ID của ngân sách chiến dịch hiện tại; bạn có thể sao chép và dán từ kết quả của bước trước.

BUDGET_ID=BUDGET_ID

Các tài nguyên tham chiếu đến các tài nguyên khác thực hiện điều đó bằng cách tên tài nguyên. Chiến dịch được tạo bên dưới tham chiếu đến campaignBudget theo tên tài nguyên có giá trị chuỗi.

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': {}
    }
  }
]
}"

Nội dung cập nhật

Cập nhật thuộc tính của đối tượng hiện có bằng các toán tử update. Phần tiếp theo ví dụ: sử dụng chiến dịch hiện tại; bạn có thể sao chép và dán từ đầu ra của bước.

CAMPAIGN_ID=CAMPAIGN_ID

Tất cả nội dung cập nhật đều yêu cầu trường updateMask, là danh sách được phân tách bằng dấu phẩy thuộc tính JSON nào nên có trong yêu cầu. Thuộc tính này nên được áp dụng dưới dạng cập nhật. Các thuộc tính có trong updateMask nhưng không có trong yêu cầu nội dung được xoá trên một đối tượng. Các thuộc tính không được liệt kê trong updateMask, nhưng có sẵn trong nội dung yêu cầu sẽ bị bỏ qua.

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'
  }
],
}"

Xóa

Các đối tượng sẽ bị xoá bằng cách chỉ định tên tài nguyên là một toán tử 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}'
  }
],
}"

Lỗi một phần

Khi có nhiều thao tác trong một yêu cầu, hãy chỉ định nếu muốn partialFailure. Nếu true, các thao tác thành công sẽ được thực hiện và hoạt động không hợp lệ sẽ trả về lỗi. Nếu là false, tất cả các thao tác trong yêu cầu sẽ thành công khi và chỉ khi tất cả các giá trị đó đều hợp lệ.

Ví dụ tiếp theo sử dụng một chiến dịch hiện tại; bạn có thể sao chép và dán từ Tạo kết quả đầu ra mẫu.

CAMPAIGN_ID=CAMPAIGN_ID

Yêu cầu sau đây chứa hai thao tác. Lần thử đầu tiên để thay đổi chiến lược giá thầu của chiến dịch đã cung cấp, và chiến dịch tiếp theo thử xóa một chiến dịch có ID không hợp lệ. Vì thao tác thứ hai dẫn đến lỗi ( mã chiến dịch không hợp lệ) và vì partialFailure được đặt thành false, nên giá trị hoạt động đầu tiên cũng không thành công và chiến lược giá thầu của chiến dịch hiện tại là chưa được cập nhật.

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'
  }
]
}"

Hoạt động được phân theo nhóm

Phương thức googleAds:mutate hỗ trợ gửi các nhóm hoạt động bằng nhiều loại tài nguyên. Bạn có thể gửi nhiều thao tác thuộc nhiều loại khác nhau tới liên kết với nhau một chuỗi các thao tác nên được thực hiện theo nhóm. Tập hợp thao tác thành công nếu không có thao tác nào không thành công hoặc tất cả đều không thành công nếu có không thành công một thao tác.

Ví dụ này minh hoạ việc tạo ngân sách chiến dịch, chiến dịch, nhóm quảng cáo và quảng cáo lại với nhau dưới dạng một tập hợp hành động duy nhất. Mỗi thao tác liên tiếp phụ thuộc vào phần trước. Nếu một thao tác không thành công thì toàn bộ nhóm thao tác sẽ không thành công.

Số nguyên âm (-1, -2, -3) được dùng làm phần giữ chỗ trong tài nguyên và được điền động trong thời gian chạy bằng kết quả từ trình tự hoạt động.

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']
        }
      }
    }
  }
]
}"

Quản lý tài khoản

Tạo tài khoản

Tạo tài khoản mới bằng phương thức createCustomerClient. Xin lưu ý rằng URL yêu cầu mã tài khoản người quản lý thay vì mã tài khoản khách hàng. Một khách hàng mới được tạo trong tài khoản người quản lý.

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'
}
}"

Liệt kê các tài khoản có thể truy cập

Sử dụng một yêu cầu GET đơn giản cho phương thức listAccessibleCustomers để lấy danh sách tài khoản Google Ads có thể truy cập bằng mã truy cập OAuth 2.0 đã cho. Không có người quản lý hoặc mã tài khoản khách hàng trong yêu cầu này.

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}" \

Tải tài sản nhị phân lên

Phương thức assets:mutate được dùng để tải lên và quản lý Thành phần. Dữ liệu nhị phân, chẳng hạn như hình ảnh, được mã hoá dưới dạng một chuỗi sử dụng bộ mã hoá base64 chuẩn có khoảng đệm. Tiêu chuẩn hoặc Chấp nhận phương thức mã hoá base64 an toàn cho URL có hoặc không có khoảng đệm.

Ví dụ này mã hoá ảnh GIF 1 pixel để mẫu ngắn gọn. Trên thực tế, Tải trọng data lớn hơn nhiều.

Sử dụng tiện ích dòng lệnh base64 (một phần của Tiện ích cốt lõi GNU) để mã hoá hình ảnh GIF 1 pixel.

base64 1pixel.gif

Giá trị được mã hoá base64 được chỉ định làm thuộc tính data trong một yêu cầu 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'
      }
    }
  }
]
}"

Các phương thức khác