Smarthands API 测试
本指南以通用的 API 测试 原则为基础，为 Equinix Smarthands API 提供具体的测试方法和示例。
Smarthands API 概述
Smarthands API 允许您以编程方式请求和管理 Equinix IBX 数据中心中的各种远程运维服务。 以下是 ECP API 与所支持的智能手类型之间的映射关系：
Smarthands 测试工作流程
在测试 Smarthands API 之前，请确保您已具备以下条件：
- 具有相应权限的有效 API 凭据
- 访问您拥有设备的 Equinix IBX 地点
- 熟悉服务工单工作流程
创建 Smarthands 服务请求
import requests
import json
# Setup authentication
auth_url = "https://api.equinix.com/oauth2/v1/token"
auth_payload = {
"grant_type": "client_credentials",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}
auth_response = requests.post(auth_url, data=auth_payload)
token = auth_response.json()["access_token"]
# Test creating a Smarthands request
base_url = "https://api.equinix.com/v1"
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
# Example: Create a cage escort request
request_payload = {
"customerReferenceNumber": "RSS41244",
"purchaseOrder": {
"number": "123455",
"purchaseOrderType": "EXISTING"
},
"ibxLocation": {
"ibx": "AM1",
"cages": [
{
"cage": "AM1:01:001MC3",
"accountNumber": "12345",
"cabinets": [
"AM1:01:001MC3:0102"
]
}
]
},
"contacts": [
{
"contactType": "ORDERING",
"userName": "jondoe@test.com"
},
{
"contactType": "NOTIFICATION",
"userName": "jondoe@test.com"
},
{
"contactType": "TECHNICAL",
"name": "John Doe",
"workPhone": "1111111",
"workPhonePrefToCall": "ANYTIME",
"mobilePhone": "1111111",
"mobilePhonePrefToCall": "ANYTIME"
}
],
"schedule": {
"scheduleType": "STANDARD",
"requestedStartDate": "2017-04-05T12:00:00Z",
"requestedCompletionDate": "2017-04-05T12:00:00Z"
},
"attachments": [
{
"id": "eb9ab7e9-3785-41e4-af24-112dff",
"name": "eb9ab7e9-3785-41e4-af24-asfsa5424"
}
],
"serviceDetails": {
"durationVisit": "30 Minutes",
"openCabinetForVisitor": false,
"scopeOfWork": "Scope of work",
"supervisionReqForVisitor": false,
"workVisitOrderNumber": "1-108050984499"
}
}
create_response = requests.post(
f"{base_url}/orders/smarthands/cageEscort",
headers=headers,
data=json.dumps(request_payload)
)
# Verify response
assert create_response.status_code == 201, f"Failed to create request: {create_response.text}"
order_number = create_response.json()["OrderNumber"]
print(f"Successfully created Smarthands request with order number: {order_number}")
正在检查请求状态
# Test retrieving request status
status_response = requests.get(
f"https://api.equinix.com/colocations/v2/orders/{order_number}",
headers=headers
)
assert status_response.status_code == 200, f"Failed to retrieve status: {status_response.text}"
status = status_response.json()["status"]
print(f"Current request status: {status}")
测试错误场景
务必对 API 实现中的错误处理进行测试：
# Test with invalid location
invalid_payload = {
"customerReferenceNumber": "RSS41244",
"purchaseOrder": {
"number": "123455",
"purchaseOrderType": "EXISTING"
},
"ibxLocation": {
"ibx": "INVALID", # Invalid IBX code
"cages": [
{
"cage": "INVALID:01:001MC3",
"accountNumber": "12345",
"cabinets": [
"INVALID:01:001MC3:0102"
]
}
]
},
"contacts": [
{
"contactType": "ORDERING",
"userName": "jondoe@test.com"
}
],
"schedule": {
"scheduleType": "STANDARD",
"requestedStartDate": "2025-08-01T10:00:00Z",
"requestedCompletionDate": "2025-08-01T12:00:00Z"
},
"serviceDetails": {
"durationVisit": "30 Minutes",
"openCabinetForVisitor": false,
"scopeOfWork": "Test invalid IBX location",
"supervisionReqForVisitor": false
}
}
error_response = requests.post(
f"{base_url}/orders/smarthands/cageEscort",
headers=headers,
data=json.dumps(invalid_payload)
)
# Verify error response
assert error_response.status_code == 400, f"Expected error but got: {error_response.status_code}"
assert "Invalid IBX location" in error_response.text, "Error message not as expected"
Smarthands API 测试最佳实践
重要提示： Equinix API 是一个生产系统，会创建真实的货运请求。请务必遵循以下测试最佳实践，以确保不会产生意外的运维工作。
- 设置专用测试账号：如果可以，请申请一个单独的测试账号。
- 首先执行只读操作：在创建/修改资源之前，先测试 GET 端点。
- 请使用清晰标记的测试请求：始终在描述前加上“TEST:”前缀，以帮助操作员识别测试请求。
- 清理测试资源：成功创建后立即取消所有测试发货。
- 请提供完整详细信息：请在您的请求中提供全面详尽的信息。
- 追踪号码：请务必提供准确的入库货物追踪号码，以确保货物得到妥善处理。
- 联系信息：请确保联系信息是最新的，并且相关人员在预定的服务时间段内可以联系到。
- 描述详情：请详细但简洁地描述您的需求，以便设施工作人员高效地完成您的请求。
自动化考量
在围绕 Smarthands API 构建自动化时：
- 实现适当的错误处理和重试机制
- 考虑实现用于状态更新的 webhook 接收器
- 内置时间窗口和服务可用性验证
- 包含所有 API 交互的审计日志
- 确保所有与发货相关的请求都自动包含跟踪信息。
- 在预定的服务窗口期内确认联系人是否可用。