网络与服务 | ArcBlock

本节详细介绍在 Blocklet Server 上管理网络和服务可用的变更操作。您可以执行配置路由规则、管理 SSL/TLS 证书、设置 Webhook 以及处理通知等操作。有关检索网络和服务数据的方法，请参阅网络与服务查询部分。

路由管理

这些变更操作允许您管理流量如何路由到您的 blocklet 和服务。

addRoutingSite

添加一个新的路由站点，这是一个针对特定域名的规则集合。

参数

input object (required) — 一个包含站点详细信息的对象。
- domain string (required) — 站点的主域名。
- type string (required) — 站点的类型。
- rules RoutingRuleInput[] — 应用于此站点的一组路由规则。

ResponseRoutingSite object — 包含新创建站点的响应对象。
- code StatusCode — 操作的状态码。
- site RoutingSite — 新创建的路由站点对象。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createRoutingSite() {
  try {
    const { site } = await client.addRoutingSite({
      input: {
        domain: 'example.com',
        type: 'blocklet',
        rules: [
          {
            from: { pathPrefix: '/' },
            to: { type: 'blocklet', did: 'z8iZuf...' },
          },
        ],
      },
    });
    console.log('路由站点已创建：', site.id);
  } catch (error) {
    console.error('创建路由站点时出错：', error);
  }
}

createRoutingSite();

addDomainAlias

向现有路由站点添加域名别名。

参数

input object (required) — 一个包含别名详细信息的对象。
- id string (required) — 要添加别名的路由站点的 ID。
- domainAlias string (required) — 要添加的域名别名。
- force boolean — 即使存在冲突，也强制添加。
- teamDid string — 与此操作关联的团队的 DID。

ResponseRoutingSite object — 包含更新后站点的响应对象。
- code StatusCode — 操作的状态码。
- site RoutingSite — 更新后的路由站点对象。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function addAlias(siteId) {
  try {
    const { site } = await client.addDomainAlias({
      input: {
        id: siteId,
        domainAlias: 'www.example.com',
      },
    });
    console.log('域名别名已添加：', site.domainAliases);
  } catch (error) {
    console.error('添加域名别名时出错：', error);
  }
}

addAlias('z2as...'); // 替换为您的站点 ID

deleteDomainAlias

从路由站点中删除域名别名。

参数

input object (required) — 一个包含删除详细信息的对象。
- id string (required) — 路由站点的 ID。
- domainAlias string (required) — 要删除的域名别名。
- teamDid string — 团队的 DID。

ResponseRoutingSite object — 包含更新后站点的响应对象。
- code StatusCode — 操作的状态码。
- site RoutingSite — 更新后的路由站点对象。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function removeAlias(siteId) {
  try {
    const { site } = await client.deleteDomainAlias({
      input: {
        id: siteId,
        domainAlias: 'www.example.com',
      },
    });
    console.log('域名别名已移除：', site.domainAliases);
  } catch (error) {
    console.error('移除域名别名时出错：', error);
  }
}

removeAlias('z2as...'); // 替换为您的站点 ID

updateRoutingSite

更新现有路由站点的属性，例如 CORS 允许的来源。

参数

input object (required) — 一个包含更新详细信息的对象。
- id string (required) — 要更新的路由站点的 ID。
- corsAllowedOrigins string[] — 一组允许的 CORS 来源。
- domain string — 站点的新主域名。

ResponseRoutingSite object — 包含更新后站点的响应对象。
- code StatusCode — 操作的状态码。
- site RoutingSite — 更新后的路由站点对象。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function updateSite(siteId) {
  try {
    const { site } = await client.updateRoutingSite({
      input: {
        id: siteId,
        corsAllowedOrigins: ['https://app.example.com'],
      },
    });
    console.log('路由站点已更新：', site.id);
  } catch (error) {
    console.error('更新路由站点时出错：', error);
  }
}

updateSite('z2as...'); // 替换为您的站点 ID

addRoutingRule

向现有站点添加新的路由规则。

参数

input object (required) — 一个包含路由规则详细信息的对象。
- id string (required) — 要添加规则的站点的 ID。
- rule RoutingRuleInput (required) — 要添加的路由规则对象。

ResponseRoutingSite object — 包含更新后站点的响应对象。
- code StatusCode — 操作的状态码。
- site RoutingSite — 更新后的路由站点对象。

updateRoutingRule

更新站点内现有的路由规则。

参数

input object (required) — 一个包含路由规则更新详细信息的对象。
- id string (required) — 包含该规则的站点的 ID。
- rule RoutingRuleInput (required) — 更新后的路由规则对象。必须提供规则的 id 字段。

ResponseRoutingSite object — 包含更新后站点的响应对象。
- code StatusCode — 操作的状态码。
- site RoutingSite — 更新后的路由站点对象。

deleteRoutingRule

从站点中删除路由规则。

参数

input object (required) — 一个包含待删除规则标识符的对象。
- id string (required) — 包含该规则的站点的 ID。
- ruleId string (required) — 要删除的规则的 ID。

ResponseRoutingSite object — 包含更新后站点的响应对象。
- code StatusCode — 操作的状态码。
- site RoutingSite — 更新后的路由站点对象。

deleteRoutingSite

删除整个路由站点。

参数

input object (required) — 一个包含要删除的站点 ID 的对象。
- id string (required) — 要删除的路由站点的 ID。

GeneralResponse object — 表示成功或失败的响应对象。
- code StatusCode — 操作的状态码。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function deleteSite(siteId) {
  try {
    await client.deleteRoutingSite({ input: { id: siteId } });
    console.log('路由站点已成功删除。');
  } catch (error) {
    console.error('删除路由站点时出错：', error);
  }
}

deleteSite('z2as...'); // 替换为您的站点 ID

takeRoutingSnapshot

创建当前路由配置的快照，可用于备份或回滚目的。

参数

input object (required) — 一个包含快照选项的对象。
- dryRun boolean — 如果为 true，则执行空运行而不创建快照。
- message string — 快照的描述性消息。

ResponseTakeRoutingSnapshot object — 包含快照哈希的响应对象。
- code StatusCode — 操作的状态码。
- hash string — 创建的快照的哈希值。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createSnapshot() {
  try {
    const { hash } = await client.takeRoutingSnapshot({
      input: { message: '重大更新前备份' },
    });
    console.log('路由快照已创建，哈希值为：', hash);
  } catch (error) {
    console.error('创建快照时出错：', error);
  }
}

createSnapshot();

证书管理

管理您域名的 SSL/TLS 证书。

addCertificate

向服务器添加自定义 SSL/TLS 证书。

参数

input object (required) — 一个包含证书详细信息的对象。
- name string (required) — 证书的唯一名称。
- privateKey string (required) — PEM 格式的私钥。
- certificate string (required) — PEM 格式的证书链。

ResponseAddNginxHttpsCert object — 表示成功或失败的响应对象。
- code StatusCode — 操作的状态码。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function uploadCertificate() {
  try {
    await client.addCertificate({
      input: {
        name: 'my-example-cert',
        privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
        certificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----',
      },
    });
    console.log('证书添加成功。');
  } catch (error) {
    console.error('添加证书时出错：', error);
  }
}

uploadCertificate();

issueLetsEncryptCert

为指定域名颁发一个新的 Let's Encrypt 证书。

参数

input object (required) — 一个包含域名和关联站点信息的对象。
- domain string (required) — 要为其颁发证书的域名。
- did string (required) — 与此域名关联的 blocklet 或团队的 DID。
- siteId string (required) — 此证书将用于的路由站点的 ID。

ResponseAddLetsEncryptCert object — 表示成功或失败的响应对象。
- code StatusCode — 操作的状态码。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function issueCert(domain, did, siteId) {
  try {
    await client.issueLetsEncryptCert({
      input: {
        domain: domain,
        did: did,
        siteId: siteId,
      },
    });
    console.log(`已为 ${domain} 启动 Let's Encrypt 证书颁发流程。`);
  } catch (error) {
    console.error('颁发证书时出错：', error);
  }
}

issueCert('example.com', 'z8iZuf...', 'z2as...');

updateCertificate

更新现有自定义证书的名称。

参数

input object (required) — 一个包含证书更新详细信息的对象。
- id string (required) — 要更新的证书的 ID。
- name string (required) — 证书的新名称。

ResponseUpdateNginxHttpsCert object — 表示成功或失败的响应对象。
- code StatusCode — 操作的状态码。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function renameCertificate(certId) {
  try {
    await client.updateCertificate({
      input: {
        id: certId,
        name: 'new-cert-name',
      },
    });
    console.log('证书更新成功。');
  } catch (error) {
    console.error('更新证书时出错：', error);
  }
}

renameCertificate('cert_xxx'); // 替换为您的证书 ID

deleteCertificate

从服务器删除自定义 SSL/TLS 证书。

参数

input object (required) — 一个包含要删除的证书 ID 的对象。
- id string (required) — 要删除的证书的 ID。

ResponseDeleteNginxHttpsCert object — 表示成功或失败的响应对象。
- code StatusCode — 操作的状态码。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function removeCertificate(certId) {
  try {
    await client.deleteCertificate({ input: { id: certId } });
    console.log('证书删除成功。');
  } catch (error) {
    console.error('删除证书时出错：', error);
  }
}

removeCertificate('cert_xxx'); // 替换为您的证书 ID

Webhook 管理

创建和管理 Webhook，以接收有关 Blocklet Server 上事件的通知。

createWebHook

创建一个新的 Webhook 发送方配置。

参数

input object (required) — 一个包含 Webhook 详细信息的对象。
- type SenderType (required) — Webhook 发送方的类型（例如，'slack'、'api'）。
- title string (required) — Webhook 的标题。
- description string — Webhook 的描述。
- params WebHookParamInput[] — Webhook 的参数数组，例如目标 URL。

ResponseCreateWebHook object — 包含新 Webhook 发送方的响应对象。
- code StatusCode — 操作的状态码。
- webhook WebHookSender — 已创建的 Webhook 发送方对象。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createWebhook() {
  try {
    const { webhook } = await client.createWebHook({
      input: {
        type: 'api',
        title: 'My Custom Webhook',
        description: '向我的服务发送通知。',
        params: [{ name: 'url', value: 'https://myservice.com/webhook' }],
      },
    });
    console.log('Webhook 已创建：', webhook.id);
  } catch (error) {
    console.error('创建 Webhook 时出错：', error);
  }
}

createWebhook();

deleteWebHook

删除现有的 Webhook 发送方。

参数

input object (required) — 一个包含要删除的 Webhook ID 的对象。
- id string (required) — 要删除的 Webhook 的 ID。

ResponseDeleteWebHook object — 表示成功或失败的响应对象。
- code StatusCode — 操作的状态码。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function deleteWebhook(webhookId) {
  try {
    await client.deleteWebHook({ input: { id: webhookId } });
    console.log('Webhook 删除成功。');
  } catch (error) {
    console.error('删除 Webhook 时出错：', error);
  }
}

deleteWebhook('wh_xxx'); // 替换为您的 Webhook ID

createWebhookEndpoint

创建一个新的 Webhook 端点以接收来自 Blocklet Server 的事件。

参数

input object (required) — 一个包含 Webhook 端点详细信息的对象。
- teamDid string (required) — 与此端点关联的团队的 DID。
- input WebhookEndpointStateInput (required) — 新端点的配置。

ResponseCreateWebhookEndpoint object — 包含新 Webhook 端点的响应对象。
- data WebhookEndpointState — 已创建的 Webhook 端点对象。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function createEndpoint() {
  try {
    const { data } = await client.createWebhookEndpoint({
      input: {
        teamDid: 'z2qa...',
        input: {
          url: 'https://myapp.com/api/webhooks',
          description: '我的应用程序端点',
          enabledEvents: [{ type: 'blocklet.started', source: 'system' }],
        },
      },
    });
    console.log('Webhook 端点已创建：', data.id);
  } catch (error) {
    console.error('创建端点时出错：', error);
  }
}

createEndpoint();

updateWebhookEndpoint

更新现有的 Webhook 端点。

参数

input object (required) — 一个包含 Webhook 端点更新详细信息的对象。
- teamDid string (required) — 团队的 DID。
- id string (required) — 要更新的端点的 ID。
- data WebhookEndpointStateInput (required) — 端点的新配置。

ResponseUpdateWebhookEndpoint object — 包含更新后 Webhook 端点的响应对象。
- data WebhookEndpointState — 更新后的 Webhook 端点对象。

deleteWebhookEndpoint

删除一个 Webhook 端点。

参数

input object (required) — 一个包含要删除的端点 ID 的对象。
- teamDid string (required) — 团队的 DID。
- id string (required) — 要删除的端点的 ID。

ResponseDeleteWebhookEndpoint object — 包含已删除 Webhook 端点的响应对象。
- data WebhookEndpointState — 已删除的 Webhook 端点对象。

retryWebhookAttempt

重试失败的 Webhook 投递尝试。

参数

input object (required) — 一个包含要重试的尝试详细信息的对象。
- teamDid string (required) — 团队的 DID。
- eventId string (required) — 事件的 ID。
- webhookId string (required) — Webhook 的 ID。
- attemptId string (required) — 失败尝试的 ID。

ResponseGetWebhookAttempt object — 包含新尝试状态的响应对象。
- data WebhookAttemptState — 新 Webhook 尝试的状态。

通知管理

在 Blocklet Server 内管理用户通知。

readNotifications

将一个或多个通知标记为已读。

参数

input object (required) — 一个包含要标记为已读的通知 ID 的对象。
- notificationIds string[] (required) — 一个通知 ID 数组。
- teamDid string — 团队 DID 范围。
- receiver string — 接收者的 DID。

ResponseReadNotifications object — 表示受影响通知数量的响应对象。
- code StatusCode — 操作的状态码。
- numAffected number — 标记为已读的通知数量。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function markAsRead(notificationIds) {
  try {
    const { numAffected } = await client.readNotifications({
      input: { notificationIds: notificationIds },
    });
    console.log(`${numAffected} 个通知已标记为已读。`);
  } catch (error) {
    console.error('将通知标记为已读时出错：', error);
  }
}

markAsRead(['notif_xxx', 'notif_yyy']);

unreadNotifications

将一个或多个通知标记为未读。

参数

input object (required) — 一个包含要标记为未读的通知 ID 的对象。
- notificationIds string[] (required) — 一个通知 ID 数组。
- teamDid string — 团队 DID 范围。
- receiver string — 接收者的 DID。

ResponseReadNotifications object — 表示受影响通知数量的响应对象。
- code StatusCode — 操作的状态码。
- numAffected number — 标记为未读的通知数量。

示例

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function markAsUnread(notificationIds) {
  try {
    const { numAffected } = await client.unreadNotifications({
      input: { notificationIds: notificationIds },
    });
    console.log(`${numAffected} 个通知已标记为未读。`);
  } catch (error) {
    console.error('将通知标记为未读时出错：', error);
  }
}

markAsUnread(['notif_xxx']);

本节介绍了网络和服务的变更操作。接下来，您可以探索用于管理备份和其他操作任务的变更操作。

下一步：数据与操作

了解如何执行与数据管理和操作任务相关的变更操作。