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 có các ví dụ về cách gọi trực tiếp các đ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 đều cần được sao chép và dán vào một khung hiển thị bash bằng lệnh curl.

Bạn cũng cần có một mã của nhà phát triển, quyền truy cập vào tài khoản thử nghiệm và một tài khoản người quản lý Google Ads chứa í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ã nhận dạng tài khoản bên dưới, sau đó sao chép và dán vào thiết bị đầu cuối để định cấu hình các biến môi trường dùng trong các ví dụ tiếp theo. Hướng dẫn Uỷ quyền đưa ra hướng dẫn về cách tạo mã truy cập 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"

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

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

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Nếu không, hai ví dụ về Mutates – Creates sẽ tạo ngân sách và chiến dịch mới.

Tìm kiếm

Hướng dẫn Sổ tay nấu ăn truy vấn chứa nhiều mẫu báo cáo tương ứng với một số màn hình mặc định của Google Ads và hoạt động với cùng các biến môi trường được dùng trong hướng dẫn này. Công cụ trình tạo truy vấn tương tác của chúng tôi cũng là một tài nguyên tuyệt vời để tạo các truy vấn tuỳ chỉnh theo cách 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 tham số pageSize có thể điều chỉnh đượ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 '{
"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'
"
}'

BB

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

BB

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

Bạn có thể gửi nhiều thao tác biến đổ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 vào mảng operations.

Tác phẩm 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 có; 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 sẽ thực hiện theo 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': {}
    }
  }
]
}"

Các bản cập nhật

Cập nhật thuộc tính của các đối tượng hiện có bằng các thao tác update. Ví dụ tiếp theo sử dụng một chiến dịch hiện có; bạn có thể sao chép và dán từ kết quả của bước trước đó.

CAMPAIGN_ID=CAMPAIGN_ID

Mọi bản cập nhật đều yêu cầu trường updateMask. Đây là một danh sách được phân tách bằng dấu phẩy gồm những thuộc tính JSON có trong yêu cầu và nên được áp dụng dưới dạng bản cập nhật. Các thuộc tính được liệt kê trong updateMask nhưng không có trong nội dung yêu cầu sẽ bị xoá trên một đối tượng. Các thuộc tính không có trong updateMask nhưng có 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 bị xoá bằng cách chỉ định tên tài nguyên của các đối tượng đó làm 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, bạn có thể chỉ định partialFailure nếu muốn. Nếu là true, các thao tác thành công sẽ được thực hiện và các thao tác 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 đều thành công khi và chỉ khi đều hợp lệ.

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

CAMPAIGN_ID=CAMPAIGN_ID

Yêu cầu sau đây chứa hai thao tác. Lần đầu tiên thay đổi chiến lược giá thầu của chiến dịch được cung cấp và lần tiếp theo cố gắng xóa một chiến dịch có mã nhận dạng 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 thao tác đầ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 không đượ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'
  }
]
}"

Toán tử được nhóm

Phương thức googleAds:mutate hỗ trợ gửi các nhóm hoạt động có 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 để liên kết với nhau một chuỗi thao tác sẽ được thực hiện theo nhóm. Tập hợp các thao tác sẽ thành công nếu không có thao tác nào thất bại hoặc tất cả đều thất bại nếu có một thao tác đơn lẻ không thành công.

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 cùng nhau dưới dạng một nhóm hành động duy nhất. Mỗi thao tác kế tiếp lại phụ thuộc vào thao tác trước đó. Nếu một thao tác bị lỗi, 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ên tài nguyên và được điền tự động trong thời gian chạy với kết quả của chuỗi thao tác.

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 phải có mã tài khoản người quản lý thay vì mã tài khoản khách hàng. Một tài khoản khách hàng mới sẽ đượ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'
}
}"

Trang thông tin có thể truy cập được

Sử dụng một yêu cầu GET đơn giản cho phương thức listAccessibleCustomers để nhận danh sách các tài khoản Google Ads có thể truy cập bằng mã truy cập OAuth 2.0 đã cho. Không được sử dụng mã tài khoản 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 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 chuỗi bằng cách sử dụng phương thức mã hoá base64 tiêu chuẩn có khoảng đệm. Chấp nhận phương thức mã hoá base64 chuẩn hoặc 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 luôn ngắn gọn. Trong 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 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