# 工作访问 API 测试 本指南以通用的 [API 测试](https://docs.equinix.com/zh-Hans/equinix-api/testing.md) 原则为基础，为 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 测试最佳实践 1. **访问时长限制**：务必确保工作访问不超过 14 天。 2. **有效笼位访问权限**：测试前请验证笼位 ID​​ 和账户权限 3. **访客信息**：测试对象包括已注册访客和未注册访客。 4. **联系方式验证**：确保联系信息和可用性设置正确 5. **时区处理**：针对国际地点的不同时区进行测试 6. **橱柜访问**：测试有无橱柜开启请求的情况 7. **采购订单类型**：测试所有三种采购订单类型（新建、现有、豁免） 8. **文件附件**：测试文档附件上传功能 9. **权限验证**：确保拥有正确的 IBX Access Services 订购权限 ## 自动化考量 围绕工作访问 API 构建自动化流程时： * 实施对最长 14 天访问持续时间的验证 * 内置访客数量限制验证（最多 50 名未注册访客） * 针对笼子访问和权限问题，制定适当的错误处理方案 * 实现用于工作访问状态更新的 webhook 接收器 * 为所有工作访问交易建立审计日志 * 创建请求前，请验证访客信息的完整性。 * 确保正确处理国际地点的时区。 * 对注册用户和非注册用户都实施正确的联系方式验证。 ## 其他资源 * [Work Visits API Reference](https://docs.equinix.com/zh-Hans/api-catalog/workvisitsv2.md) * [Smart Hands Service Guide](https://docs.equinix.com/zh-Hans/smart-hands.md) * [API Authentication](https://docs.equinix.com/zh-Hans/equinix-api/api-authentication.md) * [IBX Access Services](https://docs.equinix.com/zh-Hans/visiting-an-ibx.md)