客戶端初始化與驗證

SpaceClient 是與 DID Space 網路互動的主要介面。在您可以上傳檔案或管理資料之前，必須先使用正確的組態和驗證憑證來建立一個客戶端的實例。本指南將引導您了解初始化和驗證 SpaceClient 的各種策略。

所有組態都透過其建構函式中的單一 SpaceClientOptions 物件傳遞給客戶端。

初始化客戶端

import { SpaceClient } from '@blocklet/did-space-js';

const spaceClient = new SpaceClient({
  // ... 您的選項放在這裡
});

此組態中最關鍵的部分是 auth 物件，它決定了您的請求將如何被驗證。

驗證策略

SDK 提供了三種主要的驗證方法，旨在適應不同的使用情境。您應該選擇最適合您應用程式環境和安全需求的方法。

1. 使用端點與錢包（建議）

這是最常用且安全的方法，特別是在 Blocklet 環境中開發時，使用者的錢包隨時可用。它使用使用者的錢包來簽署請求，提供了一種強大、去中心化的驗證機制。

此方法對應 SpaceClientOptionsEndpointAuth 介面。

組態

auth object (required) — 使用錢包和端點的驗證詳細資訊。
- wallet WalletObject (required) — 錢包物件，通常從 Blocklet SDK 中取得，用於簽署請求。
- endpoint string (required) — 使用者 DID Space 和應用程式的特定 API 端點。

範例

使用錢包和端點進行初始化

import { SpaceClient } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

// 在 Blocklet 環境中，錢包很容易取得。
const wallet = getWallet();

// 該端點特定於使用者的 space 和應用程式的 DID。
const endpoint =
  'https://cedcaa27-znkomkclejcfbjaxw9knzzebmzmqrxjnn9bb.did.abtnet.io/api/space/z3T6EHN7sLhH5cty1PshDeSipeG7JNxEVaRFS/app/zNKabhhwdvVmXjtRTtSHk2YQz4pdDPStV289/';

const spaceClient = new SpaceClient({
  auth: {
    wallet: wallet,
    endpoint: endpoint,
  },
});

// 客戶端現在已準備好發送已簽署的請求。

2. 使用授權權杖

此方法適用於您擁有短期 bearer token 的情境。這在傳統的 Web 應用程式或伺服器對伺服器通訊中很常見，這些情境下可能沒有錢包。

此方法對應 SpaceClientOptionsAuthorizationAuth 介面。

組態

auth object (required) — 使用授權權杖的驗證詳細資訊。
- authorization string (required) — 隨請求發送的授權權杖（例如 JWT）。

範例

使用授權權杖進行初始化

import { SpaceClient } from '@blocklet/did-space-js';

const authToken = 'your-secure-authorization-token';

const spaceClient = new SpaceClient({
  url: 'https://www.didspaces.com/app',
  auth: {
    authorization: authToken,
  },
});

// 客戶端現在將使用此權杖進行驗證。

3. 使用存取金鑰

此方法專為需要長期存取 DID Space 的後端服務或自動化腳本而設計。它使用一個密鑰進行驗證，類似於許多雲端服務授予 API 存取權限的方式。

此方法對應 SpaceClientOptionsAccessKeyAuth 介面。

組態

auth object (required) — 使用密鑰的驗證詳細資訊。
- secretKey string (required) — 用於驗證請求的密鑰。

範例

使用密鑰進行初始化

import { SpaceClient } from '@blocklet/did-space-js';

const secretKey = 'your-long-term-secret-key';

const spaceClient = new SpaceClient({
  url: 'https://www.didspaces.com/app',
  auth: {
    secretKey: secretKey,
  },
});

// 客戶端已配置為用於伺服器端或自動化存取。

其他重要選項

除了驗證之外，SpaceClientOptions 物件還接受一些其他有用的參數。

url string (default: https://www.didspaces.com) — DID Spaces 服務的基礎 URL。SDK 會自動解析正確的應用程式掛載點。通常不需要更改此項。
delegation string — 一個 JWT 權杖，證明請求者被授權代表另一個 DID 存取該 space。
abortController AbortController — 一個 AbortController 實例，用於允許取消請求。

既然您已了解如何初始化和驗證 SpaceClient，下一步理應是學習 SDK 在底層如何保護您的請求。要深入了解安全模型，請繼續閱讀請求簽署文件。