您的第一个应用:前提条件
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
如果您尚未完成一些准备工作,请先完成,然后才能开始编写您的第一个客户端应用。
创建 Google 账号并获取 Search Ads 360 权限
若要使用 Search Ads 360 API,您需要拥有 Google 账号,并已向该账号授予 Search Ads 360 中的适当权限:
如果您还没有 Google 账号,请
创建一个。
让 Search Ads 360 代理机构管理员为您的 Google 账号
创建 Search Ads 360 用户。
要下载报告,您需要拥有目标广告客户的查看权限。
要添加或修改转化,您需要拥有目标广告客户的修改权限。在共享的 Floodlight 配置中,您需要拥有每个要上传转化数据的目标子级广告客户的修改权限。
您无需拥有父级广告客户的修改权限,也不必拥有非转化数据上传目标的子级广告客户的修改权限。如果您使用点击 ID 将转化归因于访问,请确保您对生成了点击 ID 的广告客户拥有修改权限。如果您指定的点击 ID 来自您无权修改的广告客户,请求将无法成功。
代理机构经理可以将您的账号设置为广告客户用户,让您有权访问特定广告客户;也可以为您的账号设置更高级别的访问权限,例如代理机构用户,让您有权访问代理机构中的所有广告客户。
启用 API 转化服务
如果您想上传转化数据,则需要拥有代理机构经理权限的 Search Ads 360 用户登录 Search Ads 360 界面,然后启用 API 转化服务。如需了解相关说明,请参阅 Search Ads 360 帮助中心。
为您的客户端创建 Google API 控制台项目和 OAuth 凭据
- 启动 Google API 控制台
设置工具。
设置工具会引导您完成创建项目(或使用现有项目)、启用 Search Ads 360 API 和创建 OAuth 2.0 凭据的流程。
- 在注册应用页面上,选择一个现有项目或选择创建项目。然后点击继续。
- 在 Google API 控制台启用 Search Ads 360 API 后,点击转到凭据按钮。
- 在创建凭据页面上,输入以下信息:
-
您使用的是哪个 API?:Search Ads 360 API
-
您要访问哪些数据?:用户数据
- 点击下一步按钮。
设置工具现在可帮助您创建 OAuth 2.0 客户端 ID。
- 按照设置工具中的其余步骤操作。
安装 sa360Api.py
Search Ads 360 提供了一个实用程序脚本,以简化授权设置流程。如果您想在设计和编写完整应用之前尝试发送和接收数据,也可以使用此脚本以 JSON 格式发送和接收数据。您可以复制本文档网站中的多个 JSON 示例,并将它们直接输入到脚本中。
如需安装该脚本,请执行以下操作:
- 安装 Python 2.7。
该脚本不适用于 Python 3.x。
- 安装 c网址。
- 下载 sa360Api.zip。
- 从
sa360Api.zip
中提取 sa360Api.py
。
- 将
sa360Api.py
设为可执行文件。
了解 REST 基础知识
您可以通过以下两种方式调用 Admin API:
如果您决定不使用客户端库,则需要了解 REST 的基础知识。
REST 是一种软件架构样式,可提供便利、一致的方法来请求和修改数据。
术语 REST 是“具象状态传输”的简称。在 Google API 的上下文中,指的是使用 HTTP 谓词来检索和修改由 Google 存储的数据的表示法。
在 RESTful 系统中,资源存储在数据存储区中;在客户端发送要求服务器执行特定操作(例如创建、检索、更新或删除资源)的请求之后,服务器便会执行该操作并发送响应,此响应的格式通常为所指定资源的表示法。
在 Google 的 RESTful API 中,客户端使用 HTTP 谓词(例如 POST
、GET
、PUT
或 DELETE
)指定操作。它通过以下格式的全局唯一 URI 来指定资源:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
由于所有 API 资源都具有 HTTP 可访问的唯一 URI,因此 REST 启用了数据缓存,而且经过优化以与网络的分布式基础架构一起使用。
您可能会发现 HTTP 1.1 标准文档中的方法定义十分有用;这些定义中包含了 GET
、POST
、PUT
和 DELETE
的规范。
Search Ads 360 API 中的 REST
Search Ads 360 API 操作会直接映射到 REST HTTP 动词。
Search Ads 360 API URI 的具体格式为:
https://www.googleapis.com/doubleclicksearch/v2/resourcePath?parameters
API 参考文档中总结了用于 API 中各项受支持操作的全部 URI。
了解 JSON 基础知识
如果使用 REST,则需要对请求正文使用 JSON 格式。您可以指定响应采用 JSON 或 CSV 格式。
JSON(JavaScript 对象表示法)是一种与语言无关的常见数据格式,可通过简单的文本来表示任意数据结构。如需了解详情,请参阅 json.org。
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2024-11-07。
[null,null,["最后更新时间 (UTC):2024-11-07。"],[[["\u003cp\u003eBefore using the Search Ads 360 API, ensure you have a Google Account with the necessary Search Ads 360 permissions, which may include view or edit access to specific advertisers.\u003c/p\u003e\n"],["\u003cp\u003eTo upload conversion data, the API Conversion Service must be activated by a Search Ads 360 user with Agency Manager privileges.\u003c/p\u003e\n"],["\u003cp\u003eSet up a Google API Console project and obtain OAuth credentials for your client application to authenticate and authorize API access.\u003c/p\u003e\n"],["\u003cp\u003eInstall the provided \u003ccode\u003esa360Api.py\u003c/code\u003e utility script and familiarize yourself with REST and JSON basics if you plan to interact with the API directly without client libraries.\u003c/p\u003e\n"]]],["To start coding, create a Google Account and request Search Ads 360 permissions from an Agency Manager, who will grant view or edit access to advertisers. Activate the API conversion service via the Search Ads 360 UI. Next, create a Google API Console project and OAuth 2.0 credentials. Install Python 2.7, cURL, and the `sa360Api.py` utility script. Finally, understand REST basics and JSON formatting, crucial for interacting with the API using HTTP requests.\n"],null,["# Your First App: Prerequisites\n\nBefore you can start coding your first client application, there are a few things you\nneed to do, if you haven't done them already.\n\nCreate a Google Account and get Search Ads 360 permissions\n----------------------------------------------------------\n\nTo use the Search Ads 360 API, you need a Google Account and appropriate permissions\ngranted to that account from Search Ads 360:\n\n1. If you don't already have a Google Account, [create one](https://support.google.com/accounts/answer/27441).\n\n2. Ask a Search Ads 360 **Agency Manager** to [create a Search Ads 360 user](https://support.google.com/searchads/answer/6051717) for your Google Account.\n\n To download reports, you'll need **view permission** for the advertisers\n you'll be working with.\n\n To add or edit conversions, you'll need **edit permission** for the advertisers\n you'll be working with. In a\n [shared Floodlight configuration](https://support.google.com/searchads/answer/2458167),\n you need edit permission for each child advertiser you want to upload conversions into.\n You don't need access to the parent advertiser, nor do you need access to child advertisers\n that you're not uploading conversions into. If you use click IDs to\n [attribute\n conversions to visits](/search-ads/v2/how-tos/conversions/insert#attribute-a-conversion-to-a-specific-visit), make sure you have edit access to the advertiser that generated\n the click ID. If you specify a click ID from an advertiser you don't have edit access to,\n the request will not succeed.\n\n The Agency Manager can set up your account as an **Advertiser user** with\n access to specific advertisers,\n or set up your account with a higher level of access such as **Agency user**\n with access to all advertisers in the agency.\n\nActivate the API Conversion Service\n-----------------------------------\n\n\nIf you want to upload data about conversions, a Search Ads 360 user with **Agency\nManager** privileges needs to sign in to the Search Ads 360 UI and\n**activate the API conversion service** . See the\n[Search Ads 360\nhelp center](https://support.google.com/searchads/answer/2604604#activate) for instructions.\n\nCreate a Google API Console project and OAuth credentials for your client\n-------------------------------------------------------------------------\n\n1. Start the Google API Console [setup tool](https://console.cloud.google.com/start/api?id=doubleclicksearch&credential=client_key). \n The setup tool guides you through creating a project (or using an existing project), enabling the Search Ads 360 API, and creating OAuth 2.0 credentials.\n2. On the **Register your application** page, select an existing project or select **Create a project** . Then click **Continue**.\n3. After the Google API Console enables the Search Ads 360 API, click the **Go to credentials** button.\n4. On the **Create credentials** page, enter the following information:\n - **Which API are you using?**: Search Ads 360 API\n - **What data will you be accessing?**: User data\n5. Click the **Next** button.\n\n The setup tool now offers to help you create an **OAuth 2.0 client ID**.\n6. Follow the rest of the steps in the setup tool.\n\nInstall sa360Api.py\n-------------------\n\nSearch Ads 360 provides a utility script to facilitate the process of setting up\nauthorization. You can also use this script to send and receive data in the JSON format,\nif you want to try sending and receiving data before you design and write a full\napplication. You can copy many of the JSON examples in this documentation site and input\nthem directly to the script.\n\nTo install the script:\n\n1. [Install Python](http://www.python.org/getit/) 2.7. \n The script does not work with Python 3.x.\n2. [Install cURL](http://curl.haxx.se/download.html).\n3. [Download sa360Api.zip](https://www.google.com/help/hc/downloads/sa360/sa360Api.zip).\n4. Extract `sa360Api.py` from `sa360Api.zip`.\n5. Make `sa360Api.py` executable.\n\nLearn REST basics\n-----------------\n\nThere are two ways to invoke the API:\n\n- Using [client libraries](/search-ads/v2/libraries).\n- Sending HTTP requests and parsing the responses.\n\nIf you decide not to use client libraries, you'll need to understand the basics of\nREST.\n\nREST is a style of software architecture that provides a convenient and consistent approach to requesting and modifying data.\n\nThe term REST is short for \"[Representational State Transfer](https://en.wikipedia.org/wiki/Representational_state_transfer).\" In the context of Google APIs, it refers to using HTTP verbs to retrieve and modify representations of data stored by Google.\n\nIn a RESTful system, resources are stored in a data store; a client sends a request that the server perform a particular action (such as creating, retrieving, updating, or deleting a resource), and the server performs the action and sends a response, often in the form of a representation of the specified resource.\n\nIn Google's RESTful APIs, the client specifies an action using an HTTP verb such as `POST`, `GET`, `PUT`, or `DELETE`. It specifies a resource by a globally-unique URI of the following form: \n\n```\nhttps://www.googleapis.com/apiName/apiVersion/resourcePath?parameters\n```\n\nBecause all API resources have unique HTTP-accessible URIs, REST enables data caching and is optimized to work with the web's distributed infrastructure.\n\nYou may find the [method definitions](https://tools.ietf.org/html/rfc7231#section-4.3) in the HTTP 1.1 standards documentation useful; they include specifications for `GET`, `POST`, `PUT`, and `DELETE`.\n\n### REST in the Search Ads 360 API\n\nThe Search Ads 360 API operations map directly to REST HTTP verbs.\n\nThe specific format for Search Ads 360 API URIs is: \n\n```\nhttps://www.googleapis.com/doubleclicksearch/v2/resourcePath?parameters\n```\n\n\nThe full set of URIs used for each supported operation in the API is summarized in the [API Reference](/search-ads/v2/reference).\n\nLearn JSON basics\n-----------------\n\nIf you use REST, you'll need to use the JSON format for the request bodies. You can\nspecify that the responses be either in the JSON or CSV format.\n\n\n[JSON](http://en.wikipedia.org/wiki/JSON) (JavaScript Object Notation) is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see [json.org](http://www.json.org/).\n\n\u003cbr /\u003e"]]