迁移到 Marketplace API

启用 API

与其他 Authorized Buyers 的 API 类似，您需要先启用 Marketplace API，然后才能使用它。您可以按照以下步骤启用 Marketplace API：

  1. 前往 Google API 控制台中的“已启用的 API”页面。选择您用于访问其他 Authorized Buyers API 的项目，如 Ad Exchange Buyer II 或 Real-time Bidding API。
  2. 点击 + 启用 API 和服务链接。
  3. 在搜索框中，输入“Authorized Buyers Marketplace API”，然后按 Enter 键。
  4. 在搜索结果中，选择 Authorized Buyers Marketplace API。
  5. 点击启用按钮以启用 Marketplace API。
  6. 现在，您应该可以使用此项目下创建的凭据访问 Marketplace API。

更新您的 OAuth 2.0 凭据

需要将采用 Ad Exchange Buyer II API 范围的现有 OAuth 2.0 工作流改为使用 Marketplace API 范围：

https://www.googleapis.com/auth/authorized-buyers-marketplace

我们建议使用服务帐号 OAuth 2.0 流程访问 API。所有受支持的 OAuth 2.0 流程都必须指定新的 API 范围，以便向 Google 请求可以访问 Marketplace API 的令牌。

将 Ad Exchange 买方 II API 资源映射到 Marketplace API

客户端

如果您使用 Ad Exchange Buyer II API 的 accounts.clients 资源，则可以迁移到 Marketplace API 的 buyers.clients 资源。

资源方法

Ad Exchange 买方 II API Marketplace API
accounts.clients.create buyers.clients.create
accounts.clients.get buyers.clients.get
accounts.clients.list buyers.clients.list

此方法现在支持列表过滤条件。

accounts.clients.update buyers.clients.patch

此方法现在支持使用 updateMask 参数进行部分更新。

资源字段

Ad Exchange 买方 II API Marketplace API
Client.clientAccountId Client.name

clientAccountId 是客户端资源 ID。
Client.role Client.role
Client.status Client.state
Client.clientName Client.displayName
Client.visibleToSeller Client.sellerVisible
Client.entityType

此字段已停用。
Client.entityId

此字段已停用。
Client.entityName

此字段已停用。
Client.partnerClientId Client.partnerClientId

邀请和用户

Marketplace API 将 Ad Exchange Buyer II API 的 accounts.clients.invitations 和 accounts.clients.users 资源功能整合到了单个 buyers.clients.users 资源中。

资源方法

Ad Exchange 买方 II API Marketplace API
accounts.clients.invitations.create buyers.clients.users.create
accounts.clients.invitations.get buyers.clients.users.get
accounts.clients.invitations.list buyers.clients.users.list

只有 state 设置为 INVITED 的用户才会等同于 accounts.clients.invitations.list 返回的用户。

accounts.clients.users.get buyers.clients.users.get
accounts.clients.users.list buyers.clients.users.list
accounts.clients.users.update

您无法再使用 API 修补客户用户。我们建议您使用 buyers.clients.users.delete 删除客户端用户，然后使用首选更改重新创建该用户。

资源字段

Ad Exchange 买方 II API Marketplace API
ClientUserInvitation.invitationId

此字段已停用。
ClientUserInvitation.email ClientUser.email
ClientUserInvitation.clientAccountId

对于客户用户，此字段不再存在。请改为在父客户端的名称中查看 clientAccountId。
ClientUser.userId ClientUser.name

userId 是用户资源 ID。
ClientUser.clientAccountId

对于客户用户，此字段不再存在。请改为在父客户端的名称中查看 clientAccountId。
ClientUser.status ClientUser.state
ClientUser.email ClientUser.email

产品

Marketplace API 不支持此资源及其功能。

PublisherProfiles

如果您使用 Ad Exchange Buyer II API 的 accounts.publisherProfiles 资源，则可以迁移到 Marketplace API 的 buyers.publisherProfiles 资源。

资源方法

Ad Exchange 买方 II API Marketplace API
accounts.publisherProfiles.get buyers.publisherProfiles.get
accounts.publisherProfiles.list buyers.publisherProfiles.list

此方法现在支持列表过滤条件。

资源字段

Ad Exchange 买方 II API Marketplace API
PublisherProfile.publisherProfileId PublisherProfile.name

publisherProfileId 是发布商资料资源 ID。
PublisherProfile.seller.accountId PublisherProfile.seller.accountId
PublisherProfile.seller.subAccountId PublisherProfile.seller.subAccountId
PublisherProfile.displayName PublisherProfile.displayName
PublisherProfile.domains PublisherProfile.domains
PublisherProfile.mobileApps PublisherProfile.mobileApps
PublisherProfile.logoUrl PublisherProfile.logoUrl
PublisherProfile.directDealsContact PublisherProfile.directDealsContact
PublisherProfile.programmaticDealsContact PublisherProfile.programmaticDealsContact
PublisherProfile.mediaKitUrl PublisherProfile.mediaKitUrl
PublisherProfile.samplePageUrl PublisherProfile.samplePageUrl
PublisherProfile.rateCardUrl

此字段已停用。
PublisherProfile.googlePlusUrl

此字段已停用。
PublisherProfile.overview PublisherProfile.overview
PublisherProfile.buyerPitchStatement PublisherProfile.pitchStatement
PublisherProfile.topHeadlines PublisherProfile.topHeadlines
PublisherProfile.audienceDescription PublisherProfile.audienceDescription
PublisherProfile.isParent PublisherProfile.isParent

提案和最终敲定的提案

如果您使用 Ad Exchange Buyer II API 的 accounts.proposals 资源，则可以迁移到 Marketplace API 的 buyers.proposals 资源。交易已从提案分离到 buyers.proposals.deals 子资源中。API 中不再显示已敲定的提案，这样一来，您就可以使用 buyers.finalizedDeals 资源更精细地控制已敲定的交易。

资源方法

Ad Exchange 买方 II API Marketplace API
accounts.proposals.accept buyers.proposals.accept

仅当提案的状态为 BUYER_ACCEPTANCE_REQUESTED 时，才调用 buyers.proposals.accept。
accounts.proposals.addNote buyers.proposals.addNote
accounts.proposals.cancelNegotiation buyers.proposals.cancelNegotiation
accounts.proposals.completeSetup buyers.finalizedDeals.setReadyToServe
accounts.proposals.create buyers.proposals.sendRfp
accounts.proposals.get buyers.proposals.get

请注意，该提案将不再包含与交易相关的信息。

accounts.proposals.list buyers.proposals.list

请注意，返回的提案将不再包含有关交易的信息。如果您使用列表过滤功能，请注意，Marketplace API 仅支持 列表过滤条件语法。
accounts.proposals.pause buyers.finalizedDeals.pause
accounts.proposals.resume buyers.finalizedDeals.resume
accounts.proposals.update buyers.proposals.patch

此方法现在支持使用 updateMask 参数进行部分更新。
accounts.finalizedProposals.list

使用 buyers.finalizedDeals.list 可查看指定买方帐号已敲定的交易。您现在可以使用 bidders.finalizedDeals.list 在出价方级别检索已敲定的交易。
accounts.finalizedProposals.pause

使用 buyers.finalizedDeals.pause 可暂停指定买方帐号的各个已敲定的交易。
accounts.finalizedProposals.resume

使用 buyers.finalizedDeals.resume 可恢复指定买方帐号的各个已敲定的交易。

资源字段

proposals 和 finalizedProposals 资源具有相同的 Proposal 表示法，具有类似的迁移步骤。

Ad Exchange 买方 II API Marketplace API
Proposal.proposalId Proposal.name

proposalId 是提案资源 ID。
Proposal.updateTime Proposal.updateTime
Proposal.proposalRevision

Proposal.proposalRevision 和 Deal.proposalRevision
Proposal.deals.dealId Deal.name

dealId 是交易资源 ID。
Proposal.deals.proposalId Deal.name

proposalId 是父级提案资源 ID。
Proposal.deals.createTime Deal.createTime
Proposal.deals.updateTime Deal.updateTime
Proposal.deals.createProductId

此字段已停用。
Proposal.deals.createProductRevision

此字段已停用。
Proposal.deals.displayName Deal.displayName
Proposal.deals.buyerPrivateData.referenceId

此字段已停用；目前仅在提案级别公开。
Proposal.deals.dealTerms.description Deal.description
Proposal.deals.dealTerms.brandingType

此字段已停用。
Proposal.deals.dealTerms.estimatedGrossSpend Deal.estimatedGrossSpend
Proposal.deals.dealTerms.estimatedImpressionsPerDay

此字段已停用。
Proposal.deals.dealTerms.sellerTimeZone Deal.sellerTimeZone
Proposal.deals.dealTerms.guaranteedFixedPriceTerms

Deal.programmaticGuaranteedTerms

请注意，虽然 guaranteedFixedPriceTerms.fixedPrices 是重复字段，但绝不会填充多个单个条目。因此，Marketplace API 的 programmaticGuaranteedTerms.fixedPrice 是等效的。
Proposal.deals.dealTerms.nonGuaranteedFixedPriceTerms

Deal.preferredDealTerms

请注意，虽然 nonGuaranteedFixedPriceTerms.fixedPrices 是重复字段，但绝不会填充多个单个条目。因此，Marketplace API 的 preferredDealTerms.fixedPrice 是等效的。
Proposal.deals.dealTerms.NonGuaranteedAuctionTerms

Deal.privateAuctionTerms

请注意，虽然 nonGuaranteedAuctionTerms.reservePricesPerBuyer 是重复字段，但绝不会填充多个单个条目。因此，Marketplace API 的 privateAuctionTerms.floorPrice 是等效的。
Proposal.deals.webPropertyCode

此字段已停用。
Proposal.deals.sellerContacts Proposal.sellerContacts
Proposal.deals.availableStartTime Proposal.flightStartTime
Proposal.deals.availableEndTime Proposal.flightEndTime
Proposal.deals.description Proposal.description
Proposal.deals.targetingCriterion Deal.targeting

无法再使用键来配置定位条件；不过，可以在 Deal.targeting 中找到可供定位的类别。例如，Ad Exchange 买方 II 中的 GOOG_CREATIVE_SIZE 键引用了 Marketplace API 的 Deal.targeting.inventorySizeTargeting。
Proposal.deals.targeting Deal.targeting

新增了一些定位条件类别。
Proposal.deals.creativeRestrictions.creativeFormat Deal.creativeRequirements.creativeFormat
Proposal.deals.creativeRestrictions.skippableAdType Deal.creativeRequirements.skippableAdType
Proposal.deals.creativeRestrictions.creativeSpecifications.creativeSize Deal.targeting.inventorySizeTargeting
Proposal.deals.externalDealId

此字段已停用。
Proposal.deals.syndicationProduct

此字段已停用。
Proposal.deals.creativePreApprovalPolicy Deal.creativeRequirements.creativePreApprovalPolicy
Proposal.deals.creativeSafeFrameCompatibility Deal.creativeRequirements.creativeSafeFrameCompatibility
Proposal.deals.dealServingMetadata

您可以在 FinalizedDeal.dealPausingInfo 字段中找到类似信息。
Proposal.deals.programmaticCreativeSource Deal.creativeRequirements.programmaticCreativeSource
Proposal.deals.deliveryControl Deal.deliveryControl

添加了有关如何提供交易方式的更多详情。
Proposal.deals.isSetupComplete FinalizedDeal.readyToServe

现在，只有当交易已敲定时，您才能发出信号来表明交易已可投放。使用 buyers.finalizedDeals.setReadyToServe 方法指明您敲定的有保证程序化交易已可投放。
Proposal.originatorRole Proposal.originatorRole
Proposal.seller.accountId Proposal.publisherProfile

使用发布商资料名称来识别卖方。您可以使用 buyers.publisherProfiles 资源查看发布商资料。
Proposal.seller.subAccountId Proposal.publisherProfile

使用发布商资料名称来识别卖方。您可以使用 buyers.publisherProfiles 资源查看发布商资料。
Proposal.buyer.accountId

Proposal.buyer 或 Proposal.client。

所使用的字段取决于协商买方的帐号类型。它们分别是 Real-time Bidding API buyers 资源或 Marketplace API buyers.clients 资源的资源名称。
Proposal.billedBuyer.accountId Proposal.billedBuyer

它现在是一个资源名称，引用实时出价 API 的 buyers 资源中所表示的买方帐号。
Proposal.displayName Proposal.displayName
Proposal.proposalState Proposal.state
Proposal.isRenegotiating Proposal.isRenegotiating
Proposal.buyerPrivateData Proposal.buyerPrivateData
Proposal.sellerContacts Proposal.sellerContacts
Proposal.buyerContacts Proposal.buyerContacts
Proposal.privateAuctionId

此字段已停用。
Proposal.isSetupComplete FinalizedDeal.readyToServe

现在使用 buyers.finalizedDeals 更精细地访问。
Proposal.lastUpdaterOrCommentorRole Proposal.lastUpdaterOrCommentorRole
Proposal.notes.proposalRevision

此字段已停用。
Proposal.notes.noteId

此字段已停用。
Proposal.notes.createTime Proposal.notes.createTime
Proposal.notes.creatorRole Proposal.notes.creatorRole
Proposal.notes.note Proposal.notes.note
Proposal.termsAndConditions Proposal.termsAndConditions