網路與服務 | ArcBlock

本節詳細介紹了可用於管理 Blocklet Server 上網路和服務的 mutations。您可以執行設定路由規則、管理 SSL/TLS 憑證、設定 Webhook 以及處理通知等操作。有關檢索網路和服務資料的方法，請參閱網路與服務查詢部分。

路由管理

這些 mutations 允許您管理流量如何路由到您的 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']);

本節介紹了網路和服務的 mutations。接下來，您可以探索用於管理備份和其他操作任務的 mutations。

下一步：資料與操作

了解如何執行與資料管理和操作任務相關的 mutations。