Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

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.

Để biết thêm các ví dụ chi tiết về mã, hãy xem kho lưu trữ GitHub chứa các ví dụ về mã REST.

Để xem nội dung yêu cầu và phản hồi cho từng phương thức API, hãy tham khảo tài liệu tham khảo về các điểm cuối dịch vụ cụ thể.

Ví dụ: trang tham khảo cho GoogleAdsService.Search cho thấy nội dung yêu cầu và phản hồi cho phương thức Search.

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

Tất cả các mẫu được trình bày ở đây đều được sao chép và dán vào bash shell bằng lệnh curl.

Bạn cũng cần có một dự án trên Google Cloud, quyền truy cập vào tài khoản thử nghiệm cũng được, và một 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 tài khoản và mã nhận dạng như minh hoạ, 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 được dùng trong các ví dụ tiếp theo. Hướng dẫn Uỷ quyền cung cấp hướng dẫn tạo mã truy cập OAuth 2.0.

API_VERSION="26"
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 bổ sung

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ó mã nhận dạng 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 các mã nhận dạng đó như minh hoạ.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

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

Tìm kiếm

Hướng dẫn Sổ tay 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 Google Ads mặc định và hoạt động với cùng các biến môi trường được sử dụng trong hướng dẫn này. 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 truy vấn tuỳ chỉnh theo cách tương tá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 "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'

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

Thay đổi

Bạn 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 bằng cách điền sẵn mảng operations.

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.

curl -f --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 "{
'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 tài nguyên khác bằng tên tài nguyên. Chiến dịch được tạo trong ví dụ sau đây tham chiếu đến một 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 "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 các đối tượng hiện có bằng 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

Tất cả nội dung cập nhật đều yêu cầu trường updateMask, danh sách được phân tách bằng dấu phẩy cho biết thuộc tính JSON nào phải có trong yêu cầu và được áp dụng dưới dạng nội dung cập nhật. Các thuộc tính có trong updateMask nhưng không có trong nội dung yêu cầu sẽ bị xoá khỏi đối tượng. Các thuộc tính không có trong danh sách của updateMask nhưng có trong phần 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 "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 được xoá bằng cách chỉ định tên tài nguyên của chúng dưới dạng thao tác remove.

curl -f --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 "{
'operations': [
  {
    'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}'
  }
],
}"

Không thực hiện được 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 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 false, tất cả các thao tác trong yêu cầu sẽ thành công nếu và chỉ khi tất cả các thao tác đó đề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ả của ví dụ về Tạo.

CAMPAIGN_ID=CAMPAIGN_ID

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

Thao tác được nhóm

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

Ví dụ này minh hoạ cách 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. Mỗi thao tác tiếp theo phụ thuộc vào thao tác 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ên tài nguyên và được điền động trong thời gian chạy bằng kết quả từ 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 "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

Bạn có thể tạo tài khoản, liệt kê các tài khoản có thể truy cập và tải thành phần nhị phân lê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 này 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. 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 "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 yêu cầu GET đơn giản cho phương thức listAccessibleCustomers để lấy 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. Bạn 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 "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \

Tải thành phầ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 chuỗi bằng cách sử dụng phương thức mã hoá base64 chuẩn có khoảng đệm. Hệ thống 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á một ảnh GIF 1 pixel để giữ cho 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 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 "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'
      }
    }
  }
]
}"

Lỗi thường gặp

Tiếp

Hãy dùng thử!

Ví dụ Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

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

Biến môi trường

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

Tìm kiếm

Đã phân trang

curl

GAQL

Phát trực tiếp

curl

GAQL

Thay đổi

Tạo

Nội dung cập nhật

Xóa

Không thực hiện được một phần

Thao tác được nhóm

Quản lý tài khoản

Tạo tài khoản

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

Tải thành phần nhị phân lên

Ví dụ