工作访问 API 测试
本指南以通用的 API 测试 原则为基础，为 Equinix Work Visits API 提供具体的测试方法和示例。
工作访问 API 概述
工作访问 API 允许您以编程方式安排和管理对 Equinix IBX 数据中心的工作访问，包括：
- 安排最多 14 天的工作访问
- 管理访客信息和访问权限
- 更新工作访问详情和联系方式
- 处理笼子和柜子的访问要求
- 管理包含注册用户和非注册用户的访客列表
重要提示： 工作访问仅适用于不超过 14 天的访问。超过 14 天的工作访问需要获得安全访问批准。此服务仅可由拥有 IBX 访问服务订购权限的用户预约。
工作访问测试工作流程
在测试工作访问 API 之前，请确保您已具备以下条件：
- 具有工作访问订单权限的有效 API 凭证
- 可前往设有笼位的 Equinix IBX 地点
- 您工作访问地点的有效笼位 ID
- 了解访客需求和识别流程
创建工作访问申请
import requests
import json
from datetime import datetime, timedelta
# 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 work visit request
base_url = "https://api.equinix.com/colocations/v2"
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
# Calculate visit dates (future dates)
visit_start = (datetime.utcnow() + timedelta(days=3)).isoformat() + "Z"
visit_end = (datetime.utcnow() + timedelta(days=3, hours=8)).isoformat() + "Z"
# Example: Create a work visit request
work_visit_payload = {
"description": "Monthly routine maintenance and equipment inspection",
"customerReferenceId": "WV-REF-12345",
"purchaseOrder": {
"type": "EXISTING",
"number": "PO-789456"
},
"attachments": [
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"name": "maintenance_checklist.pdf"
}
],
"contacts": [
{
"type": "TECHNICAL",
"registeredUsers": ["tech.admin@example.com"],
"availability": "WORK_HOURS",
"timezone": "America/New_York"
},
{
"type": "NOTIFICATION",
"registeredUsers": ["notifications@example.com"]
}
],
"details": {
"cages": [
{
"id": "SV1:01:001MC3",
"accountNumber": "12345",
"cabinetId": "SV1:01:001MC3:0101"
}
],
"visitStartDateTime": visit_start,
"visitEndDateTime": visit_end,
"openCabinet": True,
"visitors": [
{
"registeredUsers": ["john.doe@example.com"]
},
{
"firstName": "Jane",
"lastName": "Smith",
"companyName": "Acme Corporation",
"details": [
{
"type": "EMAIL",
"value": "jane.smith@acme.com"
},
{
"type": "MOBILE",
"value": "+1-555-123-4567"
}
]
}
]
}
}
create_response = requests.post(
f"{base_url}/orders/workVisits",
headers=headers,
data=json.dumps(work_visit_payload)
)
# Verify response
assert create_response.status_code == 201, f"Failed to create work visit: {create_response.text}"
# Extract order ID from Location header
order_number = create_response.json()["OrderNumber"]
print(f"Successfully created inbound shipment with order ID: {order_number}")
安排多日工作访问
# Example: Create a multi-day work visit (up to 14 days)
multi_day_start = (datetime.utcnow() + timedelta(days=5)).isoformat() + "Z"
multi_day_end = (datetime.utcnow() + timedelta(days=12)).isoformat() + "Z"
multi_day_payload = {
"description": "Data center migration project - Phase 1",
"customerReferenceId": "MIGRATION-PHASE1-2025",
"purchaseOrder": {
"type": "NEW",
"number": "PO-MIGRATION-001",
"amount": 5000,
"startDate": "2025-08-01",
"endDate": "2025-12-31"
},
"contacts": [
{
"type": "TECHNICAL",
"registeredUsers": ["migration.lead@example.com"],
"availability": "ANYTIME",
"timezone": "America/Los_Angeles"
}
],
"details": {
"cages": [
{
"id": "LA1:01:002MC5",
"accountNumber": "67890"
},
{
"id": "LA1:01:003MC1",
"accountNumber": "67890"
}
],
"visitStartDateTime": multi_day_start,
"visitEndDateTime": multi_day_end,
"openCabinet": False,
"visitors": [
{
"firstName": "Michael",
"lastName": "Johnson",
"companyName": "Migration Experts Inc",
"details": [
{
"type": "EMAIL",
"value": "mjohnson@migrationexperts.com"
},
{
"type": "MOBILE",
"value": "+1-310-555-9876"
}
]
},
{
"firstName": "Sarah",
"lastName": "Wilson",
"companyName": "Migration Experts Inc",
"details": [
{
"type": "EMAIL",
"value": "swilson@migrationexperts.com"
}
]
}
]
}
}
multi_day_response = requests.post(
f"{base_url}/orders/workVisits",
headers=headers,
data=json.dumps(multi_day_payload)
)
assert multi_day_response.status_code == 201, f"Failed to create multi-day work visit: {multi_day_response.text}"
print("Successfully created multi-day work visit request")
更新工作访问申请
# Test updating work visit details
if order_id:
# Update work visit with new contact information
update_payload = {
"contacts": [
{
"type": "NOTIFICATION",
"registeredUsers": ["updated.notifications@example.com", "backup.contact@example.com"]
}
],
"details": {
"visitStartDateTime": (datetime.utcnow() + timedelta(days=4)).isoformat() + "Z",
"visitEndDateTime": (datetime.utcnow() + timedelta(days=4, hours=6)).isoformat() + "Z",
"openCabinet": False
}
}
update_response = requests.patch(
f"{base_url}/orders/workVisits/{order_id}",
headers=headers,
data=json.dumps(update_payload)
)
# Verify update response
assert update_response.status_code in [202, 204], f"Failed to update work visit: {update_response.text}"
print(f"Successfully updated work visit {order_id}")
测试错误场景
务必对 API 实现中的错误处理进行测试：
# Test with missing required fields
invalid_payload = {
"description": "Invalid request test",
"details": {
"visitStartDateTime": visit_start,
"visitEndDateTime": visit_end
# Missing required 'cages' and 'visitors' fields
}
}
error_response = requests.post(
f"{base_url}/orders/workVisits",
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}"
error_data = error_response.json()
assert any("cages" in error.get("additionalInfo", {}).get("property", "") for error in error_data), "Expected cages validation error"
# Test with invalid visit duration (over 14 days)
long_visit_payload = {
"description": "Invalid long visit test",
"details": {
"cages": [{"id": "SV1:01:001MC3"}],
"visitStartDateTime": visit_start,
"visitEndDateTime": (datetime.utcnow() + timedelta(days=20)).isoformat() + "Z", # Over 14 days
"visitors": [{"registeredUsers": ["test@example.com"]}]
}
}
long_visit_response = requests.post(
f"{base_url}/orders/workVisits",
headers=headers,
data=json.dumps(long_visit_payload)
)
assert long_visit_response.status_code == 400, f"Expected duration validation error but got: {long_visit_response.status_code}"
# Test with invalid cage ID
invalid_cage_payload = {
"description": "Invalid cage test",
"details": {
"cages": [{"id": "INVALID:CAGE:ID"}],
"visitStartDateTime": visit_start,
"visitEndDateTime": visit_end,
"visitors": [{"registeredUsers": ["test@example.com"]}]
}
}
cage_error_response = requests.post(
f"{base_url}/orders/workVisits",
headers=headers,
data=json.dumps(invalid_cage_payload)
)
assert cage_error_response.status_code in [400, 403], f"Expected cage validation error but got: {cage_error_response.status_code}"
工作访问 API 测试最佳实践
- 访问时长限制：务必确保工作访问不超过 14 天。
- 有效笼位访问权限：测试前请验证笼位 ID 和账户权限
- 访客信息：测试对象包括已注册访客和未注册访客。
- 联系方式验证：确保联系信息和可用性设置正确
- 时区处理：针对国际地点的不同时区进行测试
- 橱柜访问：测试有无橱柜开启请求的情况
- 采购订单类型：测试所有三种采购订单类型（新建、现有、豁免）
- 文件附件：测试文档附件上传功能
- 权限验证：确保拥有正确的 IBX Access Services 订购权限
自动化考量
围绕工作访问 API 构建自动化流程时：
- 实施对最长 14 天访问持续时间的验证
- 内置访客数量限制验证（最多 50 名未注册访客）
- 针对笼子访问和权限问题，制定适当的错误处理方案
- 实现用于工作访问状态更新的 webhook 接收器
- 为所有工作访问交易建立审计日志
- 创建请求前，请验证访客信息的完整性。
- 确保正确处理国际地点的时区。
- 对注册用户和非注册用户都实施正确的联系方式验证。