读取应用文件

GET

apps

{app_id}

files

content

读取应用文件

curl --request GET \
  --url https://api.squarecloud.app/v2/apps/{app_id}/files/content \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.squarecloud.app/v2/apps/{app_id}/files/content"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.squarecloud.app/v2/apps/{app_id}/files/content', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/apps/{app_id}/files/content",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.squarecloud.app/v2/apps/{app_id}/files/content"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/apps/{app_id}/files/content")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
    "status": "success",
    "response": {
        "encoding": "base64",
        "data": "Y29uc29sZS5sb2coIkhlbGxvLCBTcXVhcmUgQ2xvdWQhIik7Cg=="
    }
}

string

必填

你账户的 API 密钥。你可以在账户设置中找到它。

需要具有 files:read 权限范围的 API 密钥。读取文件以 JSON 形式返回正在运行的应用中的单个文件。发送 ?encoding=base64 可获取 base64 字符串形式的文件。它用于通过 API 检查或下载最大 10 MB 的单个文件（配置、日志、小型资源），而不适用于批量传输：如需拉取应用的完整副本，请使用创建快照。

不带 encoding 时，响应为旧版的 { type: "Buffer", data: number[] } 对象。此格式自 2026 年 9 月 27 日起已弃用，并将于 2027 年 3 月 27 日移除，届时 base64 将成为默认格式。在此之前，旧格式的响应会带有 Deprecation 和 Sunset 响应头。请在每个请求中都发送 ?encoding=base64。

在读取之前，可以先调用列出文件查看有哪些可用文件。要把文件写回，请使用创建/修改文件，它通过 encoding: "base64" 接收相同的 base64 内容。在工作区共享的应用上，调用者需要具有 maintain 或 admin 角色；没有受限文件权限的成员无法读取 .env 或 .env.production，请求会在触碰文件之前就被 PERMISSION_DENIED 拒绝。

参数

string

必填

应用程序的 ID。你可以在应用程序仪表盘的 URL 中找到它。

string

必填

你想读取的文件路径，相对于应用程序的根目录。最多 256 个字符。

string

发送 base64 以 base64 字符串形式接收文件。任何其他值都会返回 INVALID_ENCODING。不带此参数时，响应使用已弃用的 Buffer 格式。

响应

string

指示调用是否成功。成功时为 success，否则为 error。

object

文件的内容。

显示展开对象

string

始终为 base64。

string

以 base64 编码的文件。

解码 data 即可得到文件的字节：

const bytes = Buffer.from(data, "base64");

const bytes = Uint8Array.fromBase64(data);
// Older browsers: Uint8Array.from(atob(data), (c) => c.charCodeAt(0))

import base64

content = base64.b64decode(data)

{
    "status": "success",
    "response": {
        "encoding": "base64",
        "data": "Y29uc29sZS5sb2coIkhlbGxvLCBTcXVhcmUgQ2xvdWQhIik7Cg=="
    }
}

常见错误

代码	HTTP	说明
`INVALID_PATH`	400	`path` 查询参数未通过校验（路径穿越、非法字符或超过 256 个字符）。
`INVALID_ENCODING`	400	`encoding` 的值不是 `base64`。
`PERMISSION_DENIED`	403	调用者缺少读取受限文件（`.env`、`.env.production`）的工作区权限。
`FILE_NOT_FOUND`	404	给定路径下不存在文件。
`FILE_TOO_LARGE`	413	文件大于 10 MB，即文件管理器可读取的上限。

相关内容

CLI：squarecloud app file read
SDK：api.apps.files.read()（JavaScript）、client.apps.files.read()（Python）、c.Apps.Files.Read()（Go）

读取应用文件

curl --request GET \
  --url https://api.squarecloud.app/v2/apps/{app_id}/files/content \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.squarecloud.app/v2/apps/{app_id}/files/content"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.squarecloud.app/v2/apps/{app_id}/files/content', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/apps/{app_id}/files/content",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.squarecloud.app/v2/apps/{app_id}/files/content"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/apps/{app_id}/files/content")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
    "status": "success",
    "response": {
        "encoding": "base64",
        "data": "Y29uc29sZS5sb2coIkhlbGxvLCBTcXVhcmUgQ2xvdWQhIik7Cg=="
    }
}

入门

账户

应用

数据库

工作区

AI

参数

响应

常见错误

相关内容

​参数

​响应

​常见错误

​相关内容

参数

响应

常见错误

相关内容