# Smarthands API 测试 本指南以通用的 [API 测试](https://docs.equinix.com/zh-Hans/equinix-api/testing.md) 原则为基础,为 Equinix Smarthands API 提供具体的测试方法和示例。 ## Smarthands API 概述[​](#smarthands-api-概述 "直接链接至Smarthands API 概述") Smarthands API 允许您以编程方式请求和管理 Equinix IBX 数据中心中的各种远程运维服务。 以下是 ECP API 与所支持的智能手类型之间的映射关系: | Smarthands Type | Description | ECP API Mapping | | ---------------------------- | --------------------------------------------- | ---------------------------------------------------------------- | | Request photos/documentation | Request cage-related photos or documentation | | | SmartHand Other | Request a Smart Hands order not listed above | | | SmartHand Cage Clean up | Request a cage clean up | | | SmartHand Shipment Unpack | Unpack inbound shipment and dispose packaging | | | SmartHand Cage Escort | Request IBX security escort | | | Equipment Install | Request equipment installation | | | Request Cables | Request cables | | | Locate Packages | Request package location | | | Run Patch Cables | Request cables run between devices | | | Patch Cable Install | Request patch cable installation | | | Move Patch Cable | Move patch cables between devices | | | Patch Cable Removal | Remove patch cables | | | Large SmartHands Order | Large cable/equipment requests | | ## Smarthands 测试工作流程[​](#smarthands-测试工作流程 "直接链接至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 测试最佳实践[​](#smarthands-api-测试最佳实践 "直接链接至Smarthands API 测试最佳实践") **重要提示**: Equinix API 是一个生产系统,会创建真实的货运请求。请务必遵循以下测试最佳实践,以确保不会产生意外的运维工作。 1. **设置专用测试账号**:如果可以,请申请一个单独的测试账号。 2. **首先执行只读操作**:在创建/修改资源之前,先测试 GET 端点。 3. **请使用清晰标记的测试请求**:始终在描述前加上“TEST:”前缀,以帮助操作员识别测试请求。 4. **清理测试资源**:成功创建后立即取消所有测试发货。 5. **请提供完整详细信息**:请在您的请求中提供全面详尽的信息。 6. **追踪号码**:请务必提供准确的入库货物追踪号码,以确保货物得到妥善处理。 7. **联系信息**:请确保联系信息是最新的,并且相关人员在预定的服务时间段内可以联系到。 8. **描述详情**:请详细但简洁地描述您的需求,以便设施工作人员高效地完成您的请求。 ## 自动化考量[​](#自动化考量 "直接链接至自动化考量") 在围绕 Smarthands API 构建自动化时: * 实现适当的错误处理和重试机制 * 考虑实现用于状态更新的 webhook 接收器 * 内置时间窗口和服务可用性验证 * 包含所有 API 交互的审计日志 * 确保所有与发货相关的请求都自动包含跟踪信息。 * 在预定的服务窗口期内确认联系人是否可用。 ## 其他资源[​](#其他资源 "直接链接至其他资源") * [Smart Hands Product Documentation](https://docs.equinix.com/zh-Hans/smart-hands.md) * [Smart Hands API Guides](https://docs.equinix.com/zh-Hans/smart-hands/smart-hands-api/order-cage-escort.md) * [Equinix API Authentication](https://docs.equinix.com/zh-Hans/equinix-api/api-authentication.md)