以下部分介绍了如何开始使用 Search Ads 360 Reporting API。
在 Google Cloud 上设置项目
如需使用 Search Ads 360 Reporting API,您需要在 Google Cloud 上为应用创建一个项目。
创建 Google 项目
Google 项目充当 Google Cloud 资源的资源容器。
- Go to the Google API Console.
- 点击 Create project。
- 输入名称或接受生成的建议。
- 确认或修改所有剩余字段。
- 点击创建。
创建 OAuth2 凭据
Search Ads 360 Reporting API 使用 OAuth 2.0 进行身份验证和授权。OAuth 凭据会让 Google 识别您的应用,并允许您生成用于管理 Search Ads 360 用户的 OAuth 令牌。
如需在 Google API Console中创建 OAuth 2.0 凭据,请执行以下操作:
- Go to the Clients page.
- 依次点击创建凭据 > OAuth 客户端 ID
- 选择您的申请类型。
- 填写表单并点击创建。
启用 Search Ads 360 Reporting API
如需使用该 API,您必须在 Google API 控制台中为项目启用 Search Ads 360 Reporting API。
如需为您的项目启用该 API,请按以下步骤操作:
- Open the API Library 中的 Google API Console。
- If prompted, select a project, or create a new one. API Library 列出了所有可用的 API,并按产品系列和热门程度分组。
- 如果列表中没有显示您要启用的 API,请使用搜索功能查找该 API,或点击该 API 所属产品系列中的查看全部。
- 选择您要启用的 API,然后点击启用按钮。
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
选择性地为项目启用结算功能
在 Google Cloud 中使用 Search Ads 360 Reporting API 无需付费。不过,每个账号的免费 Cloud 项目总数有配额限制。如果您已达到上限,可以注册一个包含免费项目配额的新 Google 账号。
要为您的项目启用结算功能,请执行以下操作:
- 访问 Billing page。
- 如果您没有有效的结算账号,请点击添加结算账号并按照说明创建一个。
启用项目的同意屏幕
如需启用项目的权限请求页面,请执行以下操作:
- 在 Google Cloud Console中打开 Branding page 。
- If prompted, select a project, or create a new one.
- 填写表单并点击保存。
创建、修改或查看重定向 URI
如需创建、查看或修改给定 OAuth 2.0 凭据的重定向 URI,请执行以下操作:
- Go to the Clients page.
- 点击相应客户。
- 查看或修改重定向 URI。
如果“客户端”页面中未列出任何客户端,则表示您的项目没有 OAuth 凭据。如需创建客户端,请点击创建客户端。
下载客户端库
建议使用 Search Ads 360 Reporting API 客户端库连接到 Search Ads 360 Reporting API。
为您的开发环境下载 Search Ads 360 Reporting API 客户端库。请按照如何设置客户端库配置文件中特定语言的说明执行操作。在大多数情况下,迁移到新版 Search Ads 360 Reporting API 客户端库时,您可以重复使用现有的配置。
一项重要变更是新增了 login-customer-id
标头。如需详细了解何时需要将此标头添加到配置中,请参阅登录客户 ID 标头。
发出首次调用
配置好客户端库后,您就可以进行首次调用了。
获取广告系列
在 IDE 中,执行以下代码:
Java
// Copyright 2022 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package sample; import com.beust.jcommander.Parameter; import com.google.ads.searchads360.v0.lib.SearchAds360Client; import com.google.ads.searchads360.v0.services.SearchAds360Row; import com.google.ads.searchads360.v0.services.SearchAds360ServiceClient; import com.google.ads.searchads360.v0.services.SearchAds360ServiceClient.SearchPagedResponse; import com.google.ads.searchads360.v0.services.SearchSearchAds360Request; /** Get campaign details. */ public class GetCampaigns { private static final int PAGE_SIZE = 200; private static class GetCampaignsParams extends CodeSampleParams { @Parameter(names = "--customerId", required = true) private String customerId; @Parameter(names = "--loginCustomerId") private String loginCustomerId; } public static void main(String[] args) { GetCampaignsParams params = new GetCampaignsParams(); if (!params.parseArguments(args)) { // Optional: You may pass the loginCustomerId on the command line or specify a loginCustomerId // here (10 digits, no dashes). If neither are set, customerId will be used as // loginCustomerId. // params.loginCustomerId = Long.parseLong("INSERT_LOGIN_CUSTOMER_ID_HERE"); } final String loginCustomerId = params.loginCustomerId; final String customerId = params.customerId; try { // Creates a SearchAds360Client with the specified loginCustomerId. If there's // no loginCustomerId, customerId will be used instead. final SearchAds360Client searchAds360Client = SearchAds360Client.newBuilder() .setLoginCustomerId(loginCustomerId == null ? customerId : loginCustomerId) .fromPropertiesFile() .build(); // Creates the Search Ads 360 Service client. SearchAds360ServiceClient client = searchAds360Client.create(); new GetCampaigns().runExample(client, customerId); } catch (Exception exception) { System.err.printf("Failed with exception: %s%n", exception); exception.printStackTrace(); System.exit(1); } } private void runExample(SearchAds360ServiceClient searchAds360ServiceClient, String customerId) { // Creates a query that retrieves all campaigns under the customerId. String query = """ SELECT campaign.name, campaign.id, campaign.status FROM campaign """; SearchSearchAds360Request request = SearchSearchAds360Request.newBuilder() .setCustomerId(customerId) .setQuery(query) .setPageSize(PAGE_SIZE) .build(); // Issues a search request. final SearchPagedResponse searchPagedResponse = searchAds360ServiceClient.search(request); for (SearchAds360Row element : searchPagedResponse.iterateAll()) { System.out.printf( "Campaign found with name '%s', ID %d, and status: %s.%n", element.getCampaign().getName(), element.getCampaign().getId(), element.getCampaign().getStatus()); } } }
Python
#!/usr/bin/env python # Copyright 2022 Google LLC # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # https://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Retrieves campaigns for a customer using a pagination search request.""" import argparse import traceback from google.ads.searchads360.v0.services.types.search_ads360_service import SearchSearchAds360Request from util_searchads360 import SearchAds360Client _DEFAULT_PAGE_SIZE = 10000 def main(client, customer_id, page_size) -> None: search_ads_360_service = client.get_service() query = """ SELECT campaign.name, campaign.id, campaign.status FROM campaign""" request = SearchSearchAds360Request() request.customer_id = customer_id request.query = query request.page_size = page_size # Issues a search request. results = search_ads_360_service.search(request=request) for row in results: campaign = row.campaign print( f'campaign "{campaign.name}" has id {campaign.id} and status {campaign.status.name}' ) if __name__ == "__main__": # SearchAds360Client will read the search-ads-360.yaml configuration file in # the home directory if none is specified. search_ads_360_client = SearchAds360Client.load_from_file() parser = argparse.ArgumentParser( description=("Retrieves campaigns for a customer.")) # Arguments to provide to run the example. parser.add_argument( "-c", "--customer_id", type=str, required=True, help="The Search Ads 360 customer ID (10 digits, no dashes).", ) parser.add_argument( "-l", "--login_customer_id", type=str, required=False, help="The Search Ads 360 login customer ID (10 digits, no dashes).", ) args = parser.parse_args() search_ads_360_client.set_ids(args.customer_id, args.login_customer_id) try: main(search_ads_360_client, args.customer_id, _DEFAULT_PAGE_SIZE) except Exception: # pylint: disable=broad-except traceback.print_exc()
控制台应输出您账号中的广告系列的列表。
使用 REST
如果您决定不使用客户端库,则需要了解如何使用 REST。
如果您之前将 REST 与旧版 Search Ads 360 API 搭配使用,您的凭据仍可用于新版 Search Ads 360 Reporting API。如需了解新端点和其他详细信息,请参阅 REST 参考文档部分。
了解详情
详细了解 Search Ads 360 Reporting API