原始查詢與訂閱

雖然 @blocklet/server-js 函式庫為大多數常見的 GraphQL 操作提供了便利的輔助方法，但在某些情況下，您可能需要更大的靈活性或存取 SDK 尚未公開的功能。對於這些進階使用案例，該函式庫允許您直接執行原始的 GraphQL 查詢和訂閱。

當您需要建構高度特定的查詢、在官方封裝前存取最新的 API 功能，或在標準方法提供的範圍之外優化資料擷取時，這種方法非常理想。

原始查詢

doRawQuery 方法讓您能夠將任何有效的 GraphQL 查詢字串傳送到 Blocklet Server API 端點。這讓您能完全控制您請求的資料及其結構。

query string (required) — 要執行的原始 GraphQL 查詢字串。
requestOptions object — 用於進階請求設定的選用物件，例如自訂標頭。

範例

以下是如何使用 doRawQuery 來擷取有關已連接節點的基本資訊。

doRawQuery 範例

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('節點名稱：', result.getNodeInfo.info.name);
    console.log('節點版本：', result.getNodeInfo.info.version);
  } catch (error) {
    console.error('執行原始查詢失敗：', error);
  }
}

getNodeVersion();

範例回應

Response Data

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

此方法會回傳一個 promise，該 promise 會解析為 GraphQL 伺服器回傳的確切 JSON 資料，讓您能夠直接存取巢狀屬性。

原始訂閱

對於即時資料更新，您可以使用 doRawSubscription 方法建立一個持久性連線並監聽伺服器推送的事件。與標準查詢不同，此方法會回傳一個訂閱物件，讓您能夠註冊事件監聽器。

query string (required) — 原始的 GraphQL 訂閱字串。

範例

此範例展示了如何訂閱 blocklet 狀態變更。每當 blocklet 的狀態更新時（例如，從「執行中」變為「已停止」），訂閱將會推送新資料。

doRawSubscription 範例

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}`);
    });

    subscription.on('error', (err) => {
      console.error('訂閱錯誤：', err);
    });

    console.log('正在監聽 blocklet 狀態變更...');
  } catch (error) {
    console.error('啟動訂閱失敗：', error);
  }
}

watchBlockletStatus();

範例資料流

當 blocklet 的狀態變更時，data 事件監聽器將會收到類似這樣的負載：

Streamed Data

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

當標準輔助方法無法滿足您的特定需求時，使用原始查詢和訂閱提供了一種與 Blocklet Server API 互動的強大方式。若要對您的原始查詢或任何其他客戶端互動進行疑難排解，請前往下一節關於偵錯的內容。