HTTP 请求

Studio 脚本需要调用第三方接口时，使用 context.http。这是服务端 Studio 脚本的正式 HTTP 入口，支持请求日志、超时、重试、trace ID 和统一错误行为。

常用参数

参数	说明
`url`	完整请求地址，例如 `https://example.com/api/orders`
`method`	HTTP 方法，常用值有 `GET`、`POST`、`PUT`、`PATCH`、`DELETE`；默认是 `GET`
`query`	URL query 参数；值会转成字符串；数组会追加多个同名参数
`headers`	请求头；常用于鉴权、API Key、content type、租户编码或自定义签名头
`json`	JSON 请求体；runtime 会自动序列化，并在需要时设置 `content-type: application/json; charset=utf-8`
`body`	原始请求体；可用于文本、`URLSearchParams`、`FormData`、`Blob`、`ArrayBuffer` 或 typed array
`expect`	响应解析方式；JSON 响应用 `json`，文本响应用 `text`
`timeoutMs`	请求超时时间，单位毫秒；默认 10000
`retry`	重试策略；不稳定的外部接口可以设置 `maxAttempts` 和 `retryableStatusCodes`
`throwOnHttpError`	默认非 2xx 响应会抛错；设置为 `false` 后由脚本自己处理错误响应
`idempotency`	外部接口支持幂等键时，用于创建或更新请求的安全重试

GET

读取数据时使用 GET。过滤条件放到 query，不要发送 body。

export default async function main(payload: StudioScriptRuntimeContextPayload, context: StudioScriptContext) {
  const response = await context.http.requestJson({
    url: 'https://example.com/api/orders',
    method: 'GET',
    query: {
      status: 'paid',
      page: 1,
    },
    timeoutMs: 10000,
  });

  return {
    data: response.data,
  };
}

POST

创建记录、提交事件或调用动作类接口时使用 POST。

const response = await context.http.requestJson({
  url: 'https://example.com/api/orders',
  method: 'POST',
  json: {
    orderNo: 'SO-1001',
    amount: 1200,
  },
  idempotency: 'order-create-SO-1001',
});

PUT

外部接口要求全量替换更新时使用 PUT。

const response = await context.http.requestJson({
  url: 'https://example.com/api/orders/SO-1001',
  method: 'PUT',
  json: {
    orderNo: 'SO-1001',
    amount: 1200,
    status: 'paid',
  },
});

PATCH

外部接口要求部分字段更新时使用 PATCH。

const response = await context.http.requestJson({
  url: 'https://example.com/api/orders/SO-1001',
  method: 'PATCH',
  json: {
    status: 'paid',
  },
});

DELETE

外部接口删除或取消资源时使用 DELETE。大多数 DELETE 接口不需要 body。

const response = await context.http.requestJson({
  url: 'https://example.com/api/orders/SO-1001',
  method: 'DELETE',
  throwOnHttpError: false,
});

if (!response.ok) {
  context.logger.warn('delete failed', response.status, response.bodyText);
}

Body：None

GET 和大多数 DELETE 请求不需要 body。

await context.http.requestJson({
  url: 'https://example.com/api/orders',
  method: 'GET',
  query: {
    status: 'paid',
  },
});

Body：JSON

普通 JSON 接口使用 json 参数，不需要自己 JSON.stringify。

await context.http.requestJson({
  url: 'https://example.com/api/orders',
  method: 'POST',
  json: {
    orderNo: 'SO-1001',
    amount: 1200,
  },
});

Body：Form URL Encoded

application/x-www-form-urlencoded 使用 URLSearchParams，常见于 token 接口。

const body = new URLSearchParams();
body.set('grant_type', 'client_credentials');
body.set('client_id', 'your-client-id');
body.set('client_secret', 'your-client-secret');

await context.http.requestJson({
  url: 'https://example.com/oauth/token',
  method: 'POST',
  headers: {
    'content-type': 'application/x-www-form-urlencoded',
  },
  body,
});

Body：Multipart Form Data

multipart/form-data 使用 FormData，常见于上传接口。不要手动设置 content-type，runtime 需要自动带上 boundary。

const form = new FormData();
form.set('name', 'orders.csv');
form.set('file', new Blob(['orderNo,amount\nSO-1001,1200\n'], {
  type: 'text/csv',
}), 'orders.csv');

await context.http.requestJson({
  url: 'https://example.com/api/uploads',
  method: 'POST',
  body: form,
});

Body：Text

纯文本、CSV、XML 或签名前后的原始 payload，可以用字符串 body。

const xml = '<order><orderNo>SO-1001</orderNo></order>';

await context.http.request({
  url: 'https://example.com/api/orders',
  method: 'POST',
  headers: {
    'content-type': 'application/xml; charset=utf-8',
  },
  body: xml,
  expect: 'text',
});

Body：Binary

接口要求二进制内容时，可以使用 Blob、ArrayBuffer 或 typed array。

import { Buffer } from 'node:buffer';

const bytes = Buffer.from('file content', 'utf8');

await context.http.requestJson({
  url: 'https://example.com/api/files',
  method: 'POST',
  headers: {
    'content-type': 'application/octet-stream',
  },
  body: bytes,
});

Headers

鉴权和第三方自定义要求放在 headers。

await context.http.requestJson({
  url: 'https://example.com/api/orders',
  method: 'GET',
  headers: {
    authorization: 'Bearer your-token',
    'x-api-key': 'your-api-key',
  },
});

自己处理 HTTP 错误

默认情况下，context.http 遇到非 2xx 响应会抛错。如果脚本要自己处理响应，设置 throwOnHttpError: false。

const response = await context.http.requestJson({
  url: 'https://example.com/api/orders',
  method: 'POST',
  json: payload,
  throwOnHttpError: false,
});

if (!response.ok) {
  context.logger.warn('third-party request failed', {
    status: response.status,
    code: response.code,
    requestId: response.requestId,
    bodyText: response.bodyText,
  });

  return {
    ok: false,
    status: response.status,
  };
}

说明

JSON 接口使用 context.http.requestJson，文本响应或自定义解析使用 context.http.request。优先使用 context.http，不要把直接 fetch 作为文档推荐写法，这样请求才能走 Studio runtime 的日志、重试、trace 和出站策略。

常用参数​

GET​

POST​

PUT​

PATCH​

DELETE​

Body：None​

Body：JSON​

Body：Form URL Encoded​

Body：Multipart Form Data​

Body：Text​

Body：Binary​

Headers​

自己处理 HTTP 错误​

说明​