方法指南
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
本页详细介绍了如何使用 API 执行常见任务。
创建用户
UserService 允许
拥有管理员权限的用户可以创建
用户任何开发者都可以做到这一点
让新用户先注册例如,如果您正在试用 API
而不是以管理员(默认
电子邮件地址),您可能需要创建几个具有如下角色的用户:
销售人员、广告投放人员或广告客户,以测试实际的工作流程。
- 新建一些 Gmail 地址,如
my.name.salesperson@gmail.com
。或者
将一个现有的非 Gmail 地址注册为新的
Google 账号。
- 使用以下新地址和所选的
Role
调用 createUsers
。
- 您可以使用 OAuth 2.0 生成访问令牌,从而以此新用户的身份进行身份验证。
获取根 AdUni
可以添加子节点的最高 AdUnit
以及允许的层次结构深度都取决于您的账号类型(标准版还是专业版)。支持修改其子节点的最顶层 AdUnit
称为有效根 AdUnit
。
如需检索有效根,请调用 NetworkService.getCurrentNetwork()
,并检查返回的 Network
对象的 effectiveRootAdUnitId
字段。
注意:不同的账号类型支持不同的层次结构模式。
查询对象
您可以使用 getObjectsByStatement()
方法按搜索条件搜索对象
其中 Object 即为特定的对象类型。本次
方法接受 PQL 查询,此查询与 SQL 查询类似,因为它允许您指定
要搜索的字段(字段名称映射到对象属性)、排序、
并限制搜索结果的范围。请参阅 PQL
此指南详细介绍了 PQL,并了解您可以使用
过滤条件。
创建订单
要创建订单,只需创建一个Order
对象并设置广告客户
销售人员和广告投放人员 ID 分配给相应的用户,请为他们指定一个唯一的名称,
然后调用 createOrders()
。结果将包含新创建的 Order
,
或错误。
示例
请参阅用于创建订单的 Java 代码示例。
创建订单项
创建新订单项的步骤如下:
- 创建一个新的
Order
对象,或使用现有对象。
- 创建一个新的
LineItem
对象,并设置轮播类型、广告素材尺寸数组
开始日期和结束日期以及其他属性。
- 创建一个新的
InventoryTargeting
对象,并指定要定位或排除的 Placement
或 AdUnit
对象。
- 将
InventoryTargeting
对象封装在新的 Targeting
对象中,并将其分配给
并将其设为LineItem
的定位属性
- 使用新对象调用订单项服务方法
createLineItems()
,并检查结果以确认对象是否已创建。
示例
请参阅用于创建订单项的 Java 代码示例。
创建广告素材
不同类型的广告素材支持不同的组件:例如,图片
广告素材支持图片的单一源文件;Flash 广告素材支持
两个基础资源文件:一个 Flash 文件和一个备份图片文件
文件无法投放。对于在第三方网站上托管的广告素材,您需要上传
引用第三方服务器上的文件的 HTML 代码段。查看您的
特定的 Creative
子类,以了解要上传哪些素材资源
创建广告素材。
示例
请参阅用于创建图片广告素材的 Java 代码示例。
修改现有对象
如需修改现有对象,请调用 getObjectsByStatement()
来查询对象,
更新返回对象中的值,然后调用 updateObjects()
。
注意:更新后的对象会完全替换现有对象,因此如果您
发送的对象中忘记设置属性值,保存的对象将
则会获取该属性的默认值,而不是之前的值。
更改对象状态
可调用 performObjectAction()
方法来更改对象状态
由服务公开此方法采用两个参数:
- 描述您要执行的操作的操作对象实例。对于
实例时,订单服务会公开几种操作,包括
ApproveOrders
、PauseOrders
、
和 ArchiveOrders
。操作对象都派生于基本操作
类。
- 对要更改的对象进行描述的 PQL 查询。您可以更改
通过指定相应的 PQL 来同时了解一个或多个对象的状态
声明。
您无法使用 API 生成广告代码;您必须使用 Google Ad Manager 网站。请参阅代码
帮助中心部分,
。
更多示例
我们的客户端库示例代码中提供更多使用多种不同语言编写的
不同的编程语言请参阅客户端库和示例代码
页面,获取使用您的编程语言编写的示例链接。
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-21。
[null,null,["最后更新时间 (UTC):2025-08-21。"],[[["\u003cp\u003eThis API allows administrators to create and manage users, orders, line items, and creatives directly within their network.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can use PQL queries to search and filter objects, similar to SQL, and modify existing objects through updates.\u003c/p\u003e\n"],["\u003cp\u003eDifferent creative types require specific assets; consult the relevant subclass documentation for details.\u003c/p\u003e\n"],["\u003cp\u003eAd tag generation is not supported by the API; use the Google Ad Manager website for this function.\u003c/p\u003e\n"],["\u003cp\u003eAccess further code samples and resources on the Client Libraries & Example Code page.\u003c/p\u003e\n"]]],["The API facilitates several core actions: creating users via `createUsers` with specified roles, and retrieving the effective root AdUnit using `NetworkService.getCurrentNetwork()`. Objects are queried using `get*Objects*ByStatement()`, and orders are created via `createOrders()`. Line items require order creation, then crafting `LineItem`, `InventoryTargeting`, and `Targeting` objects before utilizing `createLineItems()`. Creatives are created with the necessary asset uploads, while object modification involves querying, updating, and using `update*Objects*()`. Object status is changed with the `perform*Object*Action()` method. Ad tags are generated via the Google Ad Manager website.\n"],null,["# How To Guide\n\nThis page provides details on how to perform common tasks using the API.\n\nCreating Users\n--------------\n\nThe [UserService](/ad-manager/api/reference/latest/UserService) allows\na user with Administrator rights to [create\na user](/ad-manager/api/reference/latest/UserService#createUser) directly in their network. Any developer can do this without\nhaving the new user sign up first. For example, if you are trying out the API for\nthe first time, instead of performing every API call as an Administrator (the default\nfor your email address), you may want to create a few users with roles such as\nSalesperson, Trafficker, or Advertiser to test real-world workflows.\n\n1. Create some new gmail addresses such as `my.name.salesperson@gmail.com`. Alternatively, register an existing non-gmail address as a [new\n Google account](http://www.google.com/accounts/NewAccount).\n2. Call `createUsers` with that new address and the chosen [Role](/ad-manager/api/reference/latest/UserService.Role).\n3. You can authenticate as that new user, using [OAuth 2.0](/ad-manager/api/authentication) to generate your access token.\n\nGetting the Root AdUnit\n-----------------------\n\nBoth the topmost `AdUnit` to which you can add child nodes and the permitted depth of your hierarchy depend on your account type (Small Business or Premium). The topmost `AdUnit` that supports modifying its child nodes is called the effective root `AdUnit`.\n\nTo retrieve the effective root, call [NetworkService.getCurrentNetwork()](/ad-manager/api/reference/latest/NetworkService#getCurrentNetwork), and examine the `effectiveRootAdUnitId` field on the returned [Network](/ad-manager/api/reference/latest/NetworkService.Network) object.\n\n**Note:** Different account types support different hierarchy patterns.\n\nQuerying for an Object\n----------------------\n\nYou search for objects by search criteria using the `get`*Objects*`ByStatement()` method\nexposed by many services, where *Object* is a specific object type. This\nmethod takes a PQL query, which is similar to a SQL query in that it lets you specify\nfields to search on (where field names map to properties on the object), sort,\nlimit, and offset your search results. See the [PQL\nGuide](/ad-manager/api/pqlreference) to learn more about PQL, and also to learn which object fields you can\nfilter by.\n\nCreating an Order\n-----------------\n\nTo create an order, simply create an `Order` object and set the advertiser,\nsalesperson, and trafficker IDs to the appropriate users, assign a unique name,\nand call `createOrders()`. The result will include the newly created `Order`,\nor an error.\n\n**Example**\n\nSee example [Java code for creating an order](https://github.com/googleads/googleads-java-lib/blob/main/examples/admanager_axis/src/main/java/admanager/axis/v202508/orderservice/CreateOrders.java).\n\nCreating a Line Item\n--------------------\n\nHere are the steps for creating a new line item:\n\n1. Create a new `Order` object or use an existing one.\n2. Create a new `LineItem` object, and set the rotation type, creative size array, start and end dates, and other properties.\n3. Create a new `InventoryTargeting` object, and specify which `Placement` or `AdUnit` objects to target or exclude.\n4. Wrap your `InventoryTargeting` object inside a new `Targeting` object, and assign it to your `LineItem`'s targeting property.\n5. Call the lineitem service method `createLineItems()` with your new object, and examine the result to see whether your object was created.\n\n**Example**\n\nSee example [Java code for creating a line item](https://github.com/googleads/googleads-java-lib/blob/main/examples/admanager_axis/src/main/java/admanager/axis/v202508/lineitemservice/CreateLineItems.java).\n\nCreating a Creative\n-------------------\n\nDifferent types of creatives support different components: for example, an image\ncreative supports a single source file for the image; a flash creative supports\ntwo underlying asset files: a flash file and a backup image file, in case the flash\nfile cannot be served. For creatives hosted on third-party sites, you will upload\nonly an HTML snippet that references the file on the third-party server. See your\nspecific `Creative` subclass to learn what assets you'll have to upload in order\nto create your creative.\n\n**Example**\n\nSee example [Java code for creating an image creative](https://github.com/googleads/googleads-java-lib/blob/main/examples/admanager_axis/src/main/java/admanager/axis/v202508/creativeservice/CreateCreatives.java).\n\nModifying an Existing Object\n----------------------------\n\nTo modify an existing object, query for your object by calling `get`*Objects*`ByStatement()`,\nupdate the values in the returned objects, and then call `update`*Objects*`()`.\n\n**Note:** Updated objects will completely replace existing objects, so if you\nneglect to set a property value in the object that you send, the saved object will\nget the default value for that property, not the previous value.\n\nChanging Object Status\n----------------------\n\nObject status is changed by calling the `perform`*Object*`Action()` method\nexposed by your service. This method takes two parameters:\n\n- **An instance of the action object that describes what you want done.** For instance, the order service exposes several actions including `ApproveOrders`, `PauseOrders`, and `ArchiveOrders`. Action objects all derive from a base action class appropriate for your service.\n- **A PQL query describing which objects to change.** You can change the status of one or more objects at a time by specifying an appropriate PQL statement.\n\nGenerating Ad Tags\n------------------\n\nYou cannot generate ad tags using the API; instead you must use the Google Ad Manager website. See the [Tagging](https://support.google.com/admanager/answer/177207) Help Center section for\nmore information.\n\nMore Examples\n-------------\n\nYou can find many more examples in our client library sample code, in several\ndifferent programming languages. See the [Client Libraries \\& Example Code](/ad-manager/api/clients) page for a link to examples in your programming language."]]