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

インターフェースとサービス

Blockletはインターフェースを介して外部と対話し、サービスを介して強力で再利用可能な機能で強化されます。blocklet.ymlのinterfacesプロパティは、アプリケーションのウェブページ、API、およびその他のエンドポイントを公開するための基礎です。組み込みの認証サービスなどのサービス

Blockletはインターフェースを介して外部と対話し、サービスを介して強力で再利用可能な機能で強化されます。blocklet.ymlのinterfacesプロパティは、アプリケーションのウェブページ、API、およびその他のエンドポイントを公開するための基礎です。組み込みの認証サービスなどのサービスは、これらのインターフェースにアタッチして、余分な定型コードなしで共通の機能を提供できます。

このセクションでは、両方の設定方法を詳しく説明し、Blockletの明確なエントリポイントを定義し、より広範なエコシステムにシームレスに統合できるようにします。

インターフェース

interfaces配列は、Blockletのすべての公開エントリポイントを定義します。配列内の各オブジェクトは単一のインターフェースを表し、そのタイプ、場所、および動作を指定します。

インターフェーススキーマ

各インターフェースオブジェクトは、次のプロパティによって定義されます:

  • type string (required) — インターフェースのタイプ。有効な値には、web、well-known、api、healthなどがあります。Blockletはwebインターフェースを1つしか宣言できません。
  • name string (required) — インターフェースの一意で人間が読める名前（例：publicUrl、adminApi）。
  • path string (default: /) — このインターフェースを提供するBlocklet内の内部パス。
  • prefix string (default: *) — このインターフェースが公開されるパスプレフィックス。値が*（BLOCKLET_DYNAMIC_PATH_PREFIX）の場合、ユーザーは任意のパスにマウントできます。
  • protocol string (default: http) — 通信プロトコル。有効な値はhttp、https、tcp、udpです。
  • port string | object (default: PORT) — ポートマッピングを定義します。環境変数を参照する文字列（例：PORT）にすることも、固定マッピングのためにinternal（環境変数名）とexternal（ポート番号）キーを持つオブジェクトにすることもできます。
  • containerPort number — コンテナ内のポート番号。
  • hostIP string — インターフェースをホストマシン上の特定のIPにバインドします。
  • services array (default: []) — このインターフェースにアタッチするサービスのリスト。詳細は以下のサービスセクションを参照してください。
  • endpoints array (default: []) — 検出可能性と相互作用のためのメタデータを持つ特定のAPIエンドポイントを定義します。
  • cacheable array (default: []) — このインターフェース以下の相対パスのリストで、アップストリームサービスによってキャッシュ可能です。
  • proxyBehavior string (default: service) — リクエストがどのようにプロキシされるかを定義します。serviceはBlocklet Serverのサービスレイヤーを経由してルーティングし、directはそれをバイパスします。
  • pageGroups array (default: []) — ページグループ識別子のリスト。

特別なインターフェースタイプ

  • web: これはBlockletの主要なユーザー向けインターフェースです。Blockletはwebタイプのインターフェースを最大で1つしか宣言できません。
  • well-known: このタイプは、標準化されたリソース発見パス（例：/.well-known/did.json）用です。このタイプのインターフェースは、/.well-knownで始まるprefixを持つ必要があります。

例：インターフェースの定義

以下は、プライマリウェブインターフェースと別のAPIインターフェースの両方を定義するblocklet.ymlの例です。

blocklet.yml

yaml
name: my-awesome-app
did: z8iZpky2Vd3i2bE8z9f6c7g8h9j0k1m2n3p4q5r6s7t8u9v0w1x2y3z4a5b6c7d
version: 1.2.0
description: An awesome app with a web UI and an API.

interfaces:
  # ユーザーがアクセス可能なメインのウェブインターフェース
  - type: web
    name: publicUrl
    path: /
    prefix: /
    protocol: http
    port: PORT

  # 専用のAPIインターフェース
  - type: api
    name: dataApi
    path: /api
    prefix: /api
    protocol: http
    port: PORT

サービス

サービスは、Blocklet Server環境によって提供される、事前に構築された設定可能な機能です。インターフェースのservices配列で宣言するだけで、認証、認可などの機能を追加するためにインターフェースにアタッチできます。

サービススキーマ

サービスオブジェクトには2つの主要なプロパティがあります:

  • name string (required) — アタッチするサービスの名前（例：auth）。
  • config object (default: {}) — そのサービスに固有の設定オブジェクト。

組み込みサービス：auth

authサービスは、Blockletのための完全なユーザー認証および認可ソリューションを提供します。ユーザーのログイン、プロファイル管理、およびアクセス制御を処理します。

authサービスの設定

authサービスを追加すると、configオブジェクトを使用してその動作をカスタマイズできます。利用可能なオプションは次のとおりです:

  • whoCanAccess string (default: all) — 誰がインターフェースにアクセスできるかを定義します。有効な値：owner（DID Spaceの所有者のみ）、invited（所有者と招待されたユーザー）、またはall（認証されたすべてのユーザー）。
  • profileFields array (default: ["fullName", "email", "avatar"]) — ログイン時にアプリが要求するユーザープロファイル情報。有効なフィールドはfullName、email、avatar、およびphoneです。
  • allowSwitchProfile boolean (default: true) — ユーザーがアプリケーション内で異なるプロファイルを切り替えることができるかどうかを決定します。
  • blockUnauthenticated boolean (default: false) — trueの場合、サービスは認証されていないリクエストを自動的にブロックします。
  • blockUnauthorized boolean (default: false) — trueの場合、サービスはwhoCanAccessの基準を満たさない認証済みユーザーをブロックします。
  • ignoreUrls array (default: []) — 認証チェックから除外すべきURLパスまたはパターンのリスト（例：/public/**）。

例：authサービスのアタッチ

この例は、前の例のwebインターフェースをauthサービスを使用して保護する方法を示しています。

blocklet.yml

yaml
interfaces:
  - type: web
    name: publicUrl
    path: /
    prefix: /
    protocol: http
    port: PORT
    services:
      - name: auth
        config:
          whoCanAccess: invited
          blockUnauthenticated: true
          profileFields:
            - fullName
            - email
          ignoreUrls:
            - /assets/**
            - /login

この設定では、ウェブインターフェース以下のすべてのパスは、/assets/**と/loginを除いて保護されます。DID Spaceの所有者と招待されたユーザーのみが、ログイン後に保護されたページにアクセスでき、フルネームとメールアドレスの共有を求められます。

エンドポイント

インターフェース内のendpoints配列により、APIエンドポイントを明示的に定義でき、検出可能性を高め、自動化された相互作用を可能にします。

エンドポイントスキーマ

  • type string (required) — エンドポイントタイプの一意の識別子。
  • path string (required) — インターフェースのパスに対するエンドポイントへの相対パス。
  • meta object — エンドポイントに関するメタデータを含むオブジェクト。
    • vcType string — エンドポイントに関連付けられた検証可能な資格情報のタイプ。
    • payable boolean — エンドポイントが支払いを伴うかどうかを示します。
    • params array — エンドポイントが受け入れるパラメータを記述する配列。
      • name string (required) — パラメータの名前。
      • description string (required) — パラメータの説明。

インターフェースとサービスを組み合わせることで、Blockletがどのように公開されるかを明確に定義し、強力な組み込み機能で保護することができます。複数のBlockletを組み合わせてより複雑なアプリケーションを構築する方法については、次のコンポジションに関するセクションを参照してください。