メインコンテンツへスキップ

ネットワークとサービス

このセクションでは、Blocklet Server上のネットワークとサービスを管理するために利用可能なミューテーションについて詳しく説明します。ルーティングルールの設定、SSL/TLS証明書の管理、Webhookのセットアップ、通知の処理などのアクションを実行できます。ネットワークとサービスのデータを取得する方法については、ネットワークとサービスクエリセクションを参照してください。

ルーティング管理

これらのミューテーションにより、blockletやサービスへのトラフィックのルーティング方法を管理できます。

addRoutingSite

新しいルーティングサイトを追加します。これは特定のドメインのための一連のルールです。

パラメータ

  • input object (required) — サイトの詳細を含むオブジェクト。
    • domain string (required) — サイトのプライマリドメイン。
    • type string (required) — サイトのタイプ。
    • rules RoutingRuleInput[] — このサイトに適用するルーティングルールの配列。

戻り値

  • ResponseRoutingSite object — 新しく作成されたサイトを含むレスポンスオブジェクト。
    • code StatusCode — 操作のステータスコード。
    • site RoutingSite — 新しく作成されたルーティングサイトオブジェクト。

例

javascript
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 — 更新されたルーティングサイトオブジェクト。

例

javascript
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 — 更新されたルーティングサイトオブジェクト。

例

javascript
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 — 更新されたルーティングサイトオブジェクト。

例

javascript
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 — 操作のステータスコード。

例

javascript
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 — 作成されたスナップショットのハッシュ。

例

javascript
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 — 操作のステータスコード。

例

javascript
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 — 操作のステータスコード。

例

javascript
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 — 操作のステータスコード。

例

javascript
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 — 操作のステータスコード。

例

javascript
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管理

Blocklet Server上のイベントに関する通知を受け取るためのWebhookを作成および管理します。

createWebHook

新しいWebhook送信者設定を作成します。

パラメータ

  • input object (required) — Webhookの詳細を含むオブジェクト。
    • type SenderType (required) — Webhook送信者のタイプ（例：「slack」、「api」）。
    • title string (required) — Webhookのタイトル。
    • description string — Webhookの説明。
    • params WebHookParamInput[] — ターゲットURLなどのWebhookのパラメータの配列。

戻り値

  • ResponseCreateWebHook object — 新しいWebhook送信者を含むレスポンスオブジェクト。
    • code StatusCode — 操作のステータスコード。
    • webhook WebHookSender — 作成されたWebhook送信者オブジェクト。

例

javascript
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: 'Sends notifications to my service.',
        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 — 操作のステータスコード。

例

javascript
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

Blocklet Serverからイベントを受信するための新しいWebhookエンドポイントを作成します。

パラメータ

  • input object (required) — Webhookエンドポイントの詳細を含むオブジェクト。
    • teamDid string (required) — このエンドポイントに関連付けられたチームのDID。
    • input WebhookEndpointStateInput (required) — 新しいエンドポイントの設定。

戻り値

  • ResponseCreateWebhookEndpoint object — 新しいWebhookエンドポイントを含むレスポンスオブジェクト。
    • data WebhookEndpointState — 作成されたWebhookエンドポイントオブジェクト。

例

javascript
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: 'My application endpoint',
          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

1つ以上の通知を既読としてマークします。

パラメータ

  • input object (required) — 既読としてマークする通知のIDを含むオブジェクト。
    • notificationIds string[] (required) — 通知IDの配列。
    • teamDid string — チームのDIDスコープ。
    • receiver string — 受信者のDID。

戻り値

  • ResponseReadNotifications object — 影響を受けた通知の数を示すレスポンスオブジェクト。
    • code StatusCode — 操作のステータスコード。
    • numAffected number — 既読としてマークされた通知の数。

例

javascript
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

1つ以上の通知を未読としてマークします。

パラメータ

  • input object (required) — 未読としてマークする通知のIDを含むオブジェクト。
    • notificationIds string[] (required) — 通知IDの配列。
    • teamDid string — チームのDIDスコープ。
    • receiver string — 受信者のDID。

戻り値

  • ResponseReadNotifications object — 影響を受けた通知の数を示すレスポンスオブジェクト。
    • code StatusCode — 操作のステータスコード。
    • numAffected number — 未読としてマークされた通知の数。

例

javascript
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']);

このセクションでは、ネットワークとサービスに関するミューテーションについて説明しました。次に、バックアップやその他の運用タスクを管理するためのミューテーションについて見ていきましょう。

次へ: データと運用

データ管理と運用タスクに関連するミューテーションの実行方法を学びます。

続きを読む