跳到主要内容

HTTP API 快速开始

云开发 HTTP API 是一套为开发者设计的接口，旨在通过 HTTP 协议提供从客户端及服务端对云开发平台功能的访问。这些 API 允许开发者以编程方式实现用户认证、云函数、数据模型、AI 等功能，从而加速应用开发流程。

HTTP API 是通用的访问方式，您可以在任意端/语言中使用。本文将会以 Javascript 语言为例，介绍如何使用 HTTP API 。

提示

在 HTTP API 文档 中，我们为接口提供了不同语言的接入代码生成功能，包括 C++、Java、Go 等等。选择您的语言、复制粘贴，即可为您的应用接入 HTTP API 。

前置准备​

在使用特定模块的 HTTP API 之前，请确认为对应角色开启了 HTTP API 权限。

  1. 前往云后台 -> 权限控制 -> 策略管理
  2. 为角色设置各模块的开放 API （HTTP API）访问策略

1. 身份验证​

匿名登录​

const env = "your-env-id";
const deviceId = Math.random().toString(36).substring(2, 15); // 随机生成，并应缓存到客户端

const { token_type, access_token } = await (
  await fetch(
    `https://${env}.api.tcloudbasegateway.com/auth/v1/signin/anonymously`,
    {
      method: "POST",
      headers: {
        "x-device-id": deviceId,
      },
    },
  )
).json();

console.log(token_type, access_token);

用户名/密码登录​

const env = "your-env-id";
const deviceId = Math.random().toString(36).substring(2, 15); // 随机生成，并应缓存到客户端

const { token_type, access_token } = await (
  await fetch(`https://${env}.api.tcloudbasegateway.com/auth/v1/signin`, {
    method: "POST",
    headers: {
      "x-device-id": deviceId,
    },
    body: JSON.stringify({
      password: "your-password",
      username: "your-username",
    }),
  })
).json();

console.log(token_type, access_token);

详情请参考用户认证 HTTP API

2. 调用云函数​

const functonName = "add-two";
const functionParams = {
  a: 1,
  b: 101,
};

const functionResult = await (
  await fetch(
    `https://${env}.api.tcloudbasegateway.com/v1/functions/${functonName}`,
    {
      method: "POST",
      body: JSON.stringify(functionParams),
      headers: {
        "Content-Type": "application/json",
        Accept: "application/json",
        Authorization: `${token_type} ${access_token}`,
      },
    },
  )
).text();

console.log(functionResult);

详情请参考云函数 HTTP API

3. 调用云托管​

const cloudRunName = "helloworld";

const cloudRunResult = await (
  await fetch(
    `https://${env}.api.tcloudbasegateway.com/v1/cloudrun/${cloudRunName}`,
    {
      headers: { Authorization: `${token_type} ${access_token}` },
    },
  )
).text();

console.log(cloudRunResult);

详情请参考云托管 HTTP API

4. 使用云存储​

const objectId = "test.txt";

// 调用 HTTP API 获取上传信息
const [uploadInfo] = await (
  await fetch(
    `https://${env}.api.tcloudbasegateway.com/v1/storages/get-objects-upload-info
`,
    {
      headers: {
        Authorization: `${token_type} ${access_token}`,
      },
      body: JSON.stringify([{ objectId }]),
      method: "POST",
    },
  )
).json();

// 使用上传信息进行上传
const uploadResult = await fetch(uploadInfo.uploadUrl, {
  method: "PUT",
  headers: {
    Authorization: uploadInfo.authorization,
    "X-Cos-Meta-Fileid": uploadInfo.cloudObjectMeta,
    "X-Cos-Security-Token": uploadInfo.token,
  },
  body: "Hello, World!",
});

console.log(uploadResult.status, uploadResult.statusText);

详情请参考云存储 HTTP API

5. 查询数据模型​

const dataModelName = "post";
const listParams = {
  select: { $master: true },
  getCount: true,
  pageSize: 3,
};

const result = await (
  await fetch(
    `https://${env}.api.tcloudbasegateway.com/v1/model/prod/${dataModelName}/list`,
    {
      headers: {
        Authorization: `${token_type} ${access_token}`,
        "Content-Type": "application/json",
      },
      method: "POST",
      body: JSON.stringify(listParams),
    },
  )
).json();

console.log(JSON.stringify(result, null, 2));

详情请参考数据模型 HTTP API

6. 使用 AI 大模型​

const provider = "deepseek"; // 大模型提供商
const model = "deepseek-v3"; // 模型名
const llmMessages = [{ role: "user", content: "hi" }];

// 非流式生成文本
const llmGenerateResult = await (
  await fetch(
    `https://${env}.api.tcloudbasegateway.com/v1/ai/${provider}/chat/completion`,
    {
      headers: {
        Authorization: `${token_type} ${access_token}`,
        "Content-Type": "application/json",
      },
      method: "POST",
      body: JSON.stringify({
        model,
        messages: llmMessages,
        stream: false, // 非流式，stream 为 false
      }),
    },
  )
).json();

console.log(JSON.stringify(llmGenerateResult, null, 2));

// 流式生成文本
const llmStreamResult = await (
  await fetch(
    `https://${env}.api.tcloudbasegateway.com/v1/ai/${provider}/chat/completion`,
    {
      headers: {
        Authorization: `${token_type} ${access_token}`,
        "Content-Type": "application/json",
        Accept: "text/event-stream",
      },
      method: "POST",
      body: JSON.stringify({
        model,
        messages: llmMessages,
        stream: true, // 流式，stream 为 true
      }),
    },
  )
).text();

console.log(llmStreamResult);

详情请参考 AI 大模型接入 HTTP API

7. 使用智能体 (Agents)​

const agentId = "your-agent-id"; // 填写云开发平台上创建的 Agent ID
const agentMessages = [{ role: "user", content: "hi" }];

// 非流式生成文本
const agentGenerateResult = await (
  await fetch(
    `https://${env}.api.tcloudbasegateway.com/v1/aibot/openai/chat/completions`,
    {
      headers: {
        Authorization: `${token_type} ${access_token}`,
        "Content-Type": "application/json",
      },
      method: "POST",
      body: JSON.stringify({
        model: agentId,
        messages: agentMessages,
        stream: false, // 非流式，stream 为 false
      }),
    },
  )
).json();

console.log(JSON.stringify(agentGenerateResult, null, 2));

// 流式生成文本
const agentStreamResult = await (
  await fetch(
    `https://${env}.api.tcloudbasegateway.com/v1/aibot/openai/chat/completions`,
    {
      headers: {
        Authorization: `${token_type} ${access_token}`,
        "Content-Type": "application/json",
        Accept: "text/event-stream",
      },
      method: "POST",
      body: JSON.stringify({
        model: agentId,
        messages: agentMessages,
        stream: true, // 流式，stream 为 true
      }),
    },
  )
).text();

console.log(agentStreamResult);

详情请参考 AI 智能体接入 HTTP API

点击查看更多 HTTP API 详情