创建 Postman 模拟服务器
使用提供的 Postman 示例文件在本地模拟 Datadog 日志采集 API。检查请求格式和错误响应,并在不向真实 Datadog 账户发送数据的情况下运行动手示例。
先决条件
-
Postman(桌面版或 Web 版)。
-
本项目包含的 JSON 文件。开始之前请逐个下载:
文件 用途 DataPipeline-Environment.json定义可复用变量: dd_site、mock_base_url和dd_api_key。DataPipeline-postman-collection.json向 Datadog 日志采集 API( /api/v2/logs)发送真实请求。DataPipeline-MockServer-Collection.json使用 Postman 模拟服务器为相同端点配置模拟响应。
在 GitHub 上的 software 仓库 中浏览相同的文件。
1. 将文件导入 Postman
- 打开 Postman,选择 Import。
- 一次选中三个已下载的 JSON 文件。
- 在工具栏的环境选择器中,选择 Data Pipeline Environment。
导入后,Postman 会列出三个项目:
- Data Pipeline Documentation Project 发送真实请求。
- Data Pipeline Mock Server Collection 定义已保存的模拟响应。
- Data Pipeline Environment 提供两个集合共用的变量。
2. 创建模拟服务器
- 在 Postman 边栏中打开添加菜单,然后选择 Mock Server。
- 选择 Existing collection。
- 在 Collection 下选择 Data Pipeline Mock Server Collection。在 Environment 下选择 Data Pipeline Environment。
- 选择 Deploy。
- 从工作台复制模拟服务器地址。
Postman 为模拟服务器生成一个唯一地址,例如:
https://a12b34cd-1234-5678.mock.pstmn.io
3. 更新环境变量
- 转到 Environments,打开 Data Pipeline Environment。
- 找到
mock_base_url变量。 - 将占位符替换为您复制的地址:
# 修改前
https://mock-server-url-from-postman.io
# 修改后
https://a12b34cd-1234-5678.mock.pstmn.io
- 选择 Save 保存更改。
4. 发送第一个模拟请求
- 在 Data Pipeline Mock Server Collection 中打开 POST /api/v2/logs。
- 确认环境选择器显示 Data Pipeline Environment。
- 选择 Send。
模拟服务器返回模拟的 202 Accepted 响应,并重放已保存的示例正文:
{
"status": "accepted",
"message": "Log event received by mock server."
}
真实的 Datadog 日志采集 API 返回 202 Accepted 和一个空 JSON 对象({})。模拟集合返回可读对象,以便您确认模拟服务器收到了请求。
5. 测试错误响应
Datadog 会拒绝缺少必填 message 字段的事件。要重现该拒绝,请从请求正文中删除 message 字段,然后再次选择 Send。Postman 将正文与每个已保存的示例比对评分,并返回 400 示例:
{
"errors": [
{
"detail": "Malformed payload: the 'message' field is required",
"status": "400",
"title": "Bad Request"
}
]
}
要忽略正文直接返回特定示例,请添加 x-mock-response-code 请求头,其值为所需的状态代码,例如 400。
模拟服务器重放已保存的示例,从不校验凭据,因此没有可返回的 401 响应。要测试缺少 API 密钥的情况,请移除 DD-API-KEY 请求头,并从 Data Pipeline Documentation Project 发送 POST /api/v2/logs。日志采集 API 页面列出了每个错误代码对应的响应。
6. 在真实测试和模拟测试之间切换
两个集合使用相同的环境文件。要在真实测试和模拟测试之间切换,请更换您使用的集合:
| 目标 | 集合 | 基础地址变量 |
|---|---|---|
| 使用真实 Datadog 测试 | DataPipeline-postman-collection.json | {{dd_site}} → datadoghq.com |
| 在本地或离线测试 | DataPipeline-MockServer-Collection.json | {{mock_base_url}} → 您的模拟地址 |
在发送真实请求前,请在环境中设置 dd_api_key。这种方式让您在向 Datadog 账户发送数据之前验证请求和响应格式。
可视化请求流程
- Mermaid (图片)
- Mermaid (代码)
- ASCII
sequenceDiagram
participant Dev as Postman (用户)
participant Mock as Postman 模拟服务器
participant Resp as 模拟响应
Dev->>Mock: POST /api/v2/logs
Note right of Dev: 请求头:DD-API-KEY、Content-Type
Note right of Dev: 正文:JSON 日志数组
Mock-->>Resp: 对照保存的示例进行评估
Resp-->>Dev: 返回 202 Accepted 或 400/401 错误
+-----------------------+ +-----------------------+
| Postman | POST /api/v2/logs | 模拟服务器 |
| (客户端) | --------------------> | |
| | | 校验请求 |
| - DD-API-KEY 请求头 | | 对照示例 |
| - JSON 日志正文 | <-------------------- | |
| | 202 / 400 / 401 | |
+-----------------------+ +-----------------------+
在真实流量之前验证
这套模拟服务器设置演示了您在开发或编写真实 API 集成文档时使用的同一套验证模式:
- 验证请求结构 和必需请求头(
DD-API-KEY、Content-Type),然后再发送真实流量。 - 确认 JSON 载荷 符合预期模式:一个日志对象数组,每个对象都包含
message字段。 - 测试错误处理(
400、401、429),不消耗 API 配额,也不污染生产日志索引。 - 针对稳定、可复现的端点开发和验证文档 示例。
在编写 Galileo 软件开发工具包 (SDK) 文档时,同样适用这一模式。您在 dev 日志流中测试插桩后的函数,再将它们提升到 production,确保在真实用户流量经过之前正确配置评估指标。