必应广告 API 服务协议
可以使用支持 Web 服务的任何语言编写必应广告 API 应用程序。 为每个 Web 服务定义 Web 服务描述语言 (WSDL) 文档。 WSDL 定义 Web 服务提供的操作，以及客户端向操作发送和接收的请求和响应消息的格式。 请求和响应消息定义客户端与操作交换的数据的名称和类型。 有关 WSDL 的详细信息，请参阅 W3C WSDL 规范。
用于必应广告 API 的 SOAP
必应广告 API 支持简单对象访问协议 (SOAP) 。 某些语言（如 C# 和 Java）提供了从 WSDL 生成代理类的工具。 如果你选择的语言不提供生成代理类的工具，则需要生成自己的代理类或 SOAP 信封。 若要生成代理类，需要要使用的服务的 WSDL 文档的 Web 地址。 Microsoft Advertising 沙盒和生产环境各有一个唯一的地址。 这些地址还包括特定于主要必应广告 API 版本的 WSDL 的版本号。 有关最新必应广告 API 版本的生产和沙盒服务 WSDL，请参阅 必应广告 API Web 服务地址。
SOAP XML 元素顺序
创建 SOAP 请求消息时，SOAP 正文中元素的顺序至关重要。 元素的顺序必须与 Web 服务描述语言 (WSDL) 中定义的顺序相同。 如果所需的元素无序，调用将失败。 如果可选元素无序，调用可能会失败，或者元素将被忽略。 WSDL 语法显示元素的正确顺序，包含在引用内容中记录的每个请求消息、响应消息和数据对象中。 此外，每个请求和响应消息都显示一个示例 SOAP 信封。
注意
XML 区分大小写。 必须为值名称使用正确的大小写。 强类型编程语言（如 C#）可确保在编译之前具有正确的大小写。 如果未使用正确的大小写，其他语言可能不会显示编译错误;但是，代码在运行时失败。
部分成功
必应广告 API 支持部分完成添加、更新和删除操作;如果要添加、更新或删除的对象列表中的某个对象失败，则集合中其他对象的操作可能会成功。 调用获取标识符列表的 Get 操作（例如 GetKeywordsByIds 操作）且列表中的一个标识符无效时，操作将成功，并且对应于无效请求标识符的响应元素将为零。
部分更新
市场活动管理部分更新
大多数市场活动管理数据对象都支持部分更新，但并非所有市场活动管理数据对象都支持。 例如，更新 ExpandedTextAd 的 Text 属性时，只需指定 Id 和 Text 元素。 只读元素（如广告编辑状态）必须保留为零或空。 除非另有明确说明，否则可选元素可能留空，并且其现有设置保持不变。
广告扩展不支持部分更新。 任何未随更新请求一起发送的可选元素实际上将从相应的广告扩展中删除。
客户管理部分更新
客户管理服务执行实体的完整更新，因此，除了记录的必需属性外，还必须为所有不希望为零或为空的可选属性提供值。
注意
此规则的一个例外是任何对象的 ForwardCompatibilityMap 元素。 例如，如果未提供 AdvertiserAccount 的 ForwardCompatibilityMap 元素，则服务不会更新或取消任何本来由键和值对表示的属性。
在本地存储实体标识符
应维护帐户和市场活动实体的本地存储。 具体而言，应在本地存储帐户、客户、市场活动、广告组和关键字的标识符。 大多数调用都需要实体的标识符。 如果存储标识符，则无需调用获取标识符。
例如，许多市场活动管理调用都需要帐户标识符。 若要获取帐户标识符，可以使用客户管理服务。 但是，无需重复调用服务，而是在本地存储帐户标识符，以便在后续调用中使用它。
管理与进行 Web 服务调用关联的开销
以下是与每个 Web 服务调用关联的处理时间开销成本。
- 建立与 Web 服务的 HTTPS 连接。
- 对用户名和密码进行身份验证。
- 验证开发人员令牌。
无论是处理单个项还是处理一组项，这些成本都会出现。 为了最大程度地减少开销，通常应尝试在一次调用中处理尽可能多的项。 例如，对于要更新的多个市场活动，只需为要更新的多个市场活动调用 UpdateCampaigns，而不是调用 UpdateCampaigns 。 若要管理大规模数据，尤其是需要跨帐户中的多个广告组或市场活动添加或更新广告和关键字时，应使用 批量服务。 批量服务允许下载 TSV 或 CSV 文件形式的数据，根据需要对其进行修改，然后上传更改。 有关使用批量服务的详细信息，请参阅 批量下载和上传。
由于与建立与 Web 服务的连接相关的成本，因此应根据需要维护连接。 例如，如果需要请求多个报表，请对所有 Reporting Service 操作调用使用相同的 Reporting Service 客户端对象。 当不再需要该服务时，显式关闭连接。
句柄限制
限制极大量的使用量可保持所有 Microsoft Advertising 客户端的公平使用。
Ad Insight API
对于 Ad Insight 服务，限制会限制任何一个用户在一分钟内可以调用 API 的次数。
在客户级别，使用具有 60 秒窗口的滑动协议限制客户可对客户数据发出的调用次数。
如果超出服务调用限制，将看到以下错误：
- 数字错误代码： 117
- 符号错误代码：CallRateExceeded
- 消息：已超出一分钟内允许的调用数。 请减少每分钟发出的调用数。
出现此错误时，可以在等待 60 秒后，在限制下重新提交请求。
批量 API
批量服务限制可对 DownloadCampaignsByAccountIds、 DownloadCampaignsByCampaignIds 和 GetBulkUploadUrl 发出的请求数。 服务限制的详细信息是内部的，可能会更改。
如果达到服务调用限制，将看到以下错误：
- 数字错误代码： 4204
- 符号错误代码： BulkServiceNoMoreCallsPermittedForTheTimePeriod
- 消息： 当前时间段内，此帐户不再允许批量上传或下载调用。如果已达到批量上传限制，批量下载操作可能仍可用，反之亦然。
如果观察到此错误，可以在等待最多 15 分钟后重新提交请求。 有关详细信息，请参阅 批量下载最佳做法 和 批量上传最佳做法。
另请注意，在生产环境中批量上传的每个文件的大小限制为 100MB，最多为 400 万行。 对于 沙盒 ，限制为 20K 行。
市场活动管理 API
对于市场活动管理服务，限制会限制任何一个用户在一分钟内可以调用 API 的次数。
在客户级别，使用具有 60 秒窗口的滑动协议限制客户可对客户数据发出的调用次数。
如果达到服务调用限制，将看到以下错误：
- 数字错误代码： 117
- 符号错误代码：CallRateExceeded
- 消息：已超出一分钟内允许的调用数。 请减少每分钟发出的调用数。
出现此错误时，可以在等待 60 秒后，在限制下重新提交请求。
报告 API
Reporting 服务限制可向 SubmitGenerateReportRequest 发出的请求数。 服务限制的详细信息是内部的，可能会更改。
如果达到服务调用限制，将看到以下错误：
- 数字错误代码： 207
- 符号错误代码：ConcurrentRequestOverLimit
- 消息：已达到并发报表请求的最大数目。 请等到前面的报告完成，然后尝试提交新请求。
如果观察到此错误，请等待前面的报告完成，然后尝试提交新请求。