{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/zh/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"云手机文件上传与下载"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"云手机文件上传与下载","__idx":0},"children":["云手机文件上传与下载"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["本文给出完整的文件传输对接流程：将本地文件上传到云手机、从云手机导出文件、轮询异步任务，以及在超时后安全恢复。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"选择-api","__idx":1},"children":["选择 API"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"步骤"},"children":["步骤"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"开放 API"},"children":["开放 API"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"本地 API"},"children":["本地 API"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Base URL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.morelogin.com"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http://127.0.0.1:40000"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["认证"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer "]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["启用本地 Token 时传入本地 Token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["获取上传地址"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cloudphone/uploadUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/cloudphone/upload/file/signedUrl"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["下发已上传文件"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cloudphone/uploadFile"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/cloudphone/upload/file"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["查询上传结果"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cloudphone/uploadFileResult"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/cloudphone/upload/file/result"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["创建文件导出任务"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cloudphone/download"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/cloudphone/download"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["查询导出结果"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cloudphone/download/result"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/cloudphone/download/result"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["下文以开放 API 为例。本地 API 只需按上表替换 Base URL 和路径。云手机 ID 与任务 ID 必须始终按字符串保存；JavaScript 客户端不能先转换为 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Number"]},"。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"本地-api-multipart-快捷方式","__idx":2},"children":["本地 API multipart 快捷方式"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["当文件与 MoreLogin 客户端位于同一台电脑时，本地 API 还提供 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/cloudphone/uploadFile"]},"，请求类型为 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multipart/form-data"]},"："]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request POST \"http://127.0.0.1:40000/api/cloudphone/uploadFile\" \\\n --form 'id=1661515884160372' \\\n --form 'uploadDest=/Download' \\\n --form 'file=@./report.csv'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["调用方位于远程服务器、文件较大，或需要通过 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileId"]}," 明确轮询状态时，建议使用下文的预签名 URL 流程。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"上传流程","__idx":3},"children":["上传流程"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant Client as 调用方\n participant API as MoreLogin API\n participant Storage as 临时存储\n participant Phone as 云手机\n Client->>API: 1. 获取预签名地址\n API-->>Client: presignedUrl\n Client->>Storage: 2. PUT 文件内容\n Storage-->>Client: 2xx\n Client->>API: 3. 注册文件地址\n API-->>Client: fileId, status=0\n loop 直到终态\n Client->>API: 4. 查询上传结果\n API-->>Client: null / status 0、1 或 2\n end\n API->>Phone: 下发文件\n","diagramHtml":"云手机临时存储MoreLogin API调用方云手机临时存储MoreLogin API调用方loop[直到终态]1. 获取预签名地址presignedUrl2. PUT 文件内容2xx3. 注册文件地址fileId, status=04. 查询上传结果null / status 0、1 或 2下发文件","diagramHtmlDark":"云手机临时存储MoreLogin API调用方云手机临时存储MoreLogin API调用方loop[直到终态]1. 获取预签名地址presignedUrl2. PUT 文件内容2xx3. 注册文件地址fileId, status=04. 查询上传结果null / status 0、1 或 2下发文件"},"children":["sequenceDiagram\n participant Client as 调用方\n participant API as MoreLogin API\n participant Storage as 临时存储\n participant Phone as 云手机\n Client->>API: 1. 获取预签名地址\n API-->>Client: presignedUrl\n Client->>Storage: 2. PUT 文件内容\n Storage-->>Client: 2xx\n Client->>API: 3. 注册文件地址\n API-->>Client: fileId, status=0\n loop 直到终态\n Client->>API: 4. 查询上传结果\n API-->>Client: null / status 0、1 或 2\n end\n API->>Phone: 下发文件\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-获取预签名上传地址","__idx":4},"children":["1. 获取预签名上传地址"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request POST \"https://api.morelogin.com/cloudphone/uploadUrl\" \\\n --header \"Authorization: Bearer $MORELOGIN_TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"id\": \"1661515884160372\",\n \"fileName\": \"report.csv\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["响应中的地址为 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.presignedUrl"]},"。临时对象会在 7 天后自动删除，但不会删除已经成功下发到云手机内的文件。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-上传文件内容","__idx":5},"children":["2. 上传文件内容"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["直接向预签名地址上传文件，不要在这个存储请求中携带 MoreLogin Bearer Token。"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --location --request PUT \\\n --upload-file \"./report.csv\" \\\n \"$PRESIGNED_URL\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["仅在存储服务返回成功 HTTP 状态后继续。如果请求失败或超时，可以在地址仍有效时对同一个地址重试 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]},"。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-注册文件并下发到云手机","__idx":6},"children":["3. 注册文件并下发到云手机"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["传入刚刚上传的对象地址。预签名 URL 的查询参数包含凭证；如果对象存储配置允许，请在保存或记录 URL 前移除查询参数。"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"FILE_URL=\"${PRESIGNED_URL%%\\?*}\"\n\ncurl --request POST \"https://api.morelogin.com/cloudphone/uploadFile\" \\\n --header \"Authorization: Bearer $MORELOGIN_TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data \"$(jq -n \\\n --arg id '1661515884160372' \\\n --arg url \"$FILE_URL\" \\\n --arg dest '/Download' \\\n '{id: $id, url: $url, uploadDest: $dest, uploadType: 1}')\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["普通文件使用 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uploadType: 1"]},"。只有支持直播的 MP4 文件才使用 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uploadType: 2"]},"。保存响应中的 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.fileId"]},"。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-轮询上传结果","__idx":7},"children":["4. 轮询上传结果"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request POST \"https://api.morelogin.com/cloudphone/uploadFileResult\" \\\n --header \"Authorization: Bearer $MORELOGIN_TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"id\": \"1661515884160372\",\n \"fileId\": \"1661515884160111\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"data / data.status"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.status"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"含义"},"children":["含义"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"处理方式"},"children":["处理方式"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["任务暂时还不可见"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["等待后继续轮询"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["上传中"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["等待后继续轮询"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["上传成功"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["停止轮询"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["上传失败"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["停止轮询并记录 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["建议每 2 秒查询一次，并根据文件大小设置客户端总超时。状态查询超时不代表上传任务失败，应继续查询已有 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileId"]},"，不要直接重复创建任务。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"下载流程","__idx":8},"children":["下载流程"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["这里的“下载”实际是先将云手机文件导出到临时地址，再由调用方下载，是一个两阶段异步流程。"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant Client as 调用方\n participant API as MoreLogin API\n participant Phone as 云手机\n participant Storage as 临时存储\n Client->>API: 1. 创建文件导出任务（id、filePath）\n API->>Phone: 读取并导出文件\n API-->>Client: downId\n loop status=10 时继续轮询\n Client->>API: 2. 查询导出结果（id、downId）\n API-->>Client: status=10\n end\n Phone->>Storage: 写入导出文件\n API-->>Client: status=20、downUrl\n Client->>Storage: 3. GET downUrl\n Storage-->>Client: 返回文件内容\n","diagramHtml":"临时存储云手机MoreLogin API调用方临时存储云手机MoreLogin API调用方loop[status=10 时继续轮询]1. 创建文件导出任务（id、filePath）读取并导出文件downId2. 查询导出结果（id、downId）status=10写入导出文件status=20、downUrl3. GET downUrl返回文件内容","diagramHtmlDark":"临时存储云手机MoreLogin API调用方临时存储云手机MoreLogin API调用方loop[status=10 时继续轮询]1. 创建文件导出任务（id、filePath）读取并导出文件downId2. 查询导出结果（id、downId）status=10写入导出文件status=20、downUrl3. GET downUrl返回文件内容"},"children":["sequenceDiagram\n participant Client as 调用方\n participant API as MoreLogin API\n participant Phone as 云手机\n participant Storage as 临时存储\n Client->>API: 1. 创建文件导出任务（id、filePath）\n API->>Phone: 读取并导出文件\n API-->>Client: downId\n loop status=10 时继续轮询\n Client->>API: 2. 查询导出结果（id、downId）\n API-->>Client: status=10\n end\n Phone->>Storage: 写入导出文件\n API-->>Client: status=20、downUrl\n Client->>Storage: 3. GET downUrl\n Storage-->>Client: 返回文件内容\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["如果轮询返回 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["30"]},"（失败）或 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["40"]},"（已取消），应停止流程，不要再请求 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["downUrl"]},"。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-创建文件导出任务","__idx":9},"children":["1. 创建文件导出任务"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["必须传入包含文件名的 Android 绝对路径。"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request POST \"https://api.morelogin.com/cloudphone/download\" \\\n --header \"Authorization: Bearer $MORELOGIN_TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"id\": \"1661515884160372\",\n \"filePath\": \"/sdcard/Download/report.csv\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["保存 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.downId"]},"。该请求只创建导出任务，不会直接返回文件内容。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-轮询并获取下载地址","__idx":10},"children":["2. 轮询并获取下载地址"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request POST \"https://api.morelogin.com/cloudphone/download/result\" \\\n --header \"Authorization: Bearer $MORELOGIN_TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"id\": \"1661515884160372\",\n \"downId\": \"1661515884160999\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"data.status"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.status"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"含义"},"children":["含义"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"处理方式"},"children":["处理方式"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["10"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["执行中"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["等待后继续轮询"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["20"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["成功"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["使用 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.downUrl"]}," 下载"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["30"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["失败"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["停止并记录 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["40"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["已取消"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["停止；仍有需要时再创建新任务"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["状态为 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["20"]}," 后应尽快下载文件："]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --location \"$DOWN_URL\" --output \"./report.csv\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["不要向 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["downUrl"]}," 携带 MoreLogin Bearer Token。预签名上传地址和下载地址都应视为敏感信息，不应写入应用日志。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"完整-python-示例","__idx":11},"children":["完整 Python 示例"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["下面的代码需要安装 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requests"]},"。它会同时检查 HTTP 状态和业务 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]},"，设置轮询截止时间，并始终复用服务端返回的任务 ID。"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import os\nimport time\nfrom pathlib import Path\n\nimport requests\n\nBASE_URL = \"https://api.morelogin.com\"\nTOKEN = os.environ[\"MORELOGIN_TOKEN\"]\nPHONE_ID = \"1661515884160372\"\nHEADERS = {\"Authorization\": f\"Bearer {TOKEN}\"}\n\n\ndef api_post(path, payload):\n response = requests.post(\n f\"{BASE_URL}{path}\", json=payload, headers=HEADERS, timeout=30\n )\n response.raise_for_status()\n body = response.json()\n if body.get(\"code\") != 0:\n raise RuntimeError(\n f\"API error code={body.get('code')} msg={body.get('msg')} \"\n f\"requestId={body.get('requestId')}\"\n )\n return body\n\n\ndef wait_for(path, payload, terminal, timeout=300):\n deadline = time.monotonic() + timeout\n while time.monotonic() < deadline:\n body = api_post(path, payload)\n data = body.get(\"data\")\n if data is not None and data.get(\"status\") in terminal:\n return body\n time.sleep(2)\n raise TimeoutError(f\"Timed out while polling {path}; keep the task ID\")\n\n\ndef upload_to_phone(local_path, destination=\"/Download\"):\n path = Path(local_path)\n signed = api_post(\n \"/cloudphone/uploadUrl\", {\"id\": PHONE_ID, \"fileName\": path.name}\n )\n presigned_url = signed[\"data\"][\"presignedUrl\"]\n with path.open(\"rb\") as stream:\n put_response = requests.put(presigned_url, data=stream, timeout=120)\n put_response.raise_for_status()\n\n object_url = presigned_url.split(\"?\", 1)[0]\n created = api_post(\n \"/cloudphone/uploadFile\",\n {\n \"id\": PHONE_ID,\n \"url\": object_url,\n \"uploadDest\": destination,\n \"uploadType\": 1,\n },\n )\n file_id = created[\"data\"][\"fileId\"]\n result = wait_for(\n \"/cloudphone/uploadFileResult\",\n {\"id\": PHONE_ID, \"fileId\": file_id},\n terminal={1, 2},\n )\n if result[\"data\"][\"status\"] != 1:\n raise RuntimeError(f\"Upload failed; requestId={result.get('requestId')}\")\n return file_id\n\n\ndef download_from_phone(remote_path, local_path):\n created = api_post(\n \"/cloudphone/download\", {\"id\": PHONE_ID, \"filePath\": remote_path}\n )\n down_id = created[\"data\"][\"downId\"]\n result = wait_for(\n \"/cloudphone/download/result\",\n {\"id\": PHONE_ID, \"downId\": down_id},\n terminal={20, 30, 40},\n )\n if result[\"data\"][\"status\"] != 20:\n raise RuntimeError(f\"Download export failed; requestId={result.get('requestId')}\")\n\n with requests.get(result[\"data\"][\"downUrl\"], stream=True, timeout=120) as response:\n response.raise_for_status()\n with open(local_path, \"wb\") as output:\n for chunk in response.iter_content(1024 * 1024):\n if chunk:\n output.write(chunk)\n return down_id\n\n\nupload_to_phone(\"./report.csv\")\ndownload_from_phone(\"/sdcard/Download/report.csv\", \"./downloaded-report.csv\")\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"生产接入检查清单","__idx":12},"children":["生产接入检查清单"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["必须检查 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code == 0"]},"，HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," 本身不代表业务操作成功。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},"、",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileId"]}," 和 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["downId"]}," 始终按字符串保存。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["状态查询使用退避重试。创建任务请求超时后，如果已经获得任务 ID，应先查询原任务。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["限制并发传输数量，并遵守",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/zh/api-reference/getting-started/rate-limits"},"children":["限流规则"]},"。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["大文件传输前检查本地文件大小与云手机剩余存储空间。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["为排障记录 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]},"、端点、云手机 ID、任务 ID 和终态，但必须脱敏 Token 与签名 URL。"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["完整字段定义参见",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/zh/api-reference/cloud-phone/open-api"},"children":["云手机开放 API"]},"和",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/zh/api-reference/cloud-phone/local-api"},"children":["云手机本地 API"]},"；通用轮询与重试规则参见",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/zh/api-reference/getting-started/async-operations"},"children":["异步操作"]},"。"]}]},"headings":[{"value":"云手机文件上传与下载","id":"云手机文件上传与下载","depth":1},{"value":"选择 API","id":"选择-api","depth":2},{"value":"本地 API multipart 快捷方式","id":"本地-api-multipart-快捷方式","depth":3},{"value":"上传流程","id":"上传流程","depth":2},{"value":"1. 获取预签名上传地址","id":"1-获取预签名上传地址","depth":3},{"value":"2. 上传文件内容","id":"2-上传文件内容","depth":3},{"value":"3. 注册文件并下发到云手机","id":"3-注册文件并下发到云手机","depth":3},{"value":"4. 轮询上传结果","id":"4-轮询上传结果","depth":3},{"value":"下载流程","id":"下载流程","depth":2},{"value":"1. 创建文件导出任务","id":"1-创建文件导出任务","depth":3},{"value":"2. 轮询并获取下载地址","id":"2-轮询并获取下载地址","depth":3},{"value":"完整 Python 示例","id":"完整-python-示例","depth":2},{"value":"生产接入检查清单","id":"生产接入检查清单","depth":2}],"frontmatter":{"seo":{"title":"云手机文件上传与下载"}},"lastModified":"2026-09-02T11:22:17.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/zh/api-reference/cloud-phone/file-transfer","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}