Raw クエリとサブスクリプション

@blocklet/server-js ライブラリは、ほとんどの一般的な GraphQL 操作に便利なヘルパーメソッドを提供していますが、SDK を通じてまだ公開されていない機能へのアクセスや、より高い柔軟性が必要な状況があります。これらの高度なユースケースのために、このライブラリでは生の GraphQL クエリとサブスクリプションを直接実行できます。

このアプローチは、非常に特定のクエリを構築する必要がある場合、公式にラップされる前の最新の API 機能にアクセスする場合、または標準メソッドが提供するもの以上にデータ取得を最適化する場合に最適です。

Raw クエリ

doRawQuery メソッドを使用すると、有効な GraphQL クエリストリングを Blocklet Server API エンドポイントに送信できます。これにより、リクエストするデータとその構造を完全に制御できます。

query string (required) — 実行する生の GraphQL クエリストリング。
requestOptions object — カスタムヘッダーなどの高度なリクエスト設定のためのオプションのオブジェクト。

例

以下は doRawQuery を使用して、接続されているノードの基本情報を取得する方法です。

doRawQuery Example

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

const client = new BlockletServerClient();

async function getNodeVersion() {
  try {
    const query = `{
      getNodeInfo {
        info {
          version
          name
        }
      }
    }`;

    const result = await client.doRawQuery(query);
    console.log('Node Name:', result.getNodeInfo.info.name);
    console.log('Node Version:', result.getNodeInfo.info.version);
  } catch (error) {
    console.error('Failed to execute raw query:', error);
  }
}

getNodeVersion();

レスポンス例

Response Data

{
  "getNodeInfo": {
    "info": {
      "version": "1.8.22",
      "name": "My Dev Node"
    }
  }
}

このメソッドは、GraphQL サーバーから返された正確な JSON データで解決されるプロミスを返します。これにより、ネストされたプロパティに直接アクセスできます。

Raw サブスクリプション

リアルタイムのデータ更新には、doRawSubscription メソッドを使用して永続的な接続を確立し、サーバーからプッシュされたイベントをリッスンできます。標準のクエリとは異なり、このメソッドはイベントリスナーを登録できるサブスクリプションオブジェクトを返します。

query string (required) — 生の GraphQL サブスクリプション文字列。

例

この例では、blocklet のステータスの変更をサブスクライブする方法を示します。サブスクリプションは、blocklet のステータスが更新されるたび（例：「running」から「stopped」へ）に新しいデータをプッシュします。

doRawSubscription Example

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

const client = new BlockletServerClient();

async function watchBlockletStatus() {
  try {
    const subscriptionQuery = `subscription {
      blockletStatusChanged {
        did
        status
      }
    }`;

    const subscription = await client.doRawSubscription(subscriptionQuery);

    subscription.on('data', (data) => {
      const { did, status } = data.blockletStatusChanged;
      console.log(`Blocklet ${did} status changed to: ${status}`);
    });

    subscription.on('error', (err) => {
      console.error('Subscription error:', err);
    });

    console.log('Listening for blocklet status changes...');
  } catch (error) {
    console.error('Failed to start subscription:', error);
  }
}

watchBlockletStatus();

データストリームの例

blocklet のステータスが変更されると、data イベントリスナーは次のようなペイロードを受け取ります：

Streamed Data

{
  "blockletStatusChanged": {
    "did": "z8iZpA6x3M4Jz3J6iK9y6L4oE3nF2aH5c8g7",
    "status": "stopped"
  }
}

Raw クエリとサブスクリプションを使用すると、標準のヘルパーメソッドが特定のニーズを満たさない場合に、Blocklet Server API と対話する強力な方法が提供されます。Raw クエリやその他のクライアントとのやり取りのトラブルシューティングについては、次のセクションデバッグに進んでください。