迁移到 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. 点击 ENABLE 按钮以启用 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 Buyer 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 Buyer 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 Buyer 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 Buyer 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 Buyer 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 是一个重复字段，但其填充的内容从未超过 1 条。因此，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 Buyer 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

现在，此资源名称是指买方账号（如 Real-time Bidding 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