実行と環境 | ArcBlock

blocklet.yml 内の実行と環境の設定は、Blocklet がどのように実行されるかの設計図です。それは、必要なランタイムを指定し、システム要件を定義し、ユーザーに設定オプションを公開し、Blocklet のライフサイクルにフックします。このセクションを正しく設定することは、ポータブルで、堅牢で、ユーザーフレンドリーなアプリケーションを作成するために不可欠です。

このセクションでは、engine、docker、requirements、environments、scripts、および timeout の6つの主要な領域について説明します。

エンジン (engine)

このプロパティは、blocklet の実行エンジンを指定し、ランタイムとそれをどのように起動するかを定義します。ほとんどの JavaScript ベースの blocklet では、インタープリタとして node を指定し、(blocklet.yml のルートで定義された) main プロパティがエントリポイントとして機能します。

シンプルな Node.js エンジン

name: my-node-blocklet
main: build/index.js
engine:
  interpreter: node

また、複数のプラットフォームをサポートするためにエンジン設定の配列を提供することもできます。これはバイナリ配布に最適です。

マルチプラットフォームエンジン設定

# ... 他のプロパティ
engine:
  - platform: linux
    interpreter: binary
    source: ./bin/server-linux
  - platform: darwin
    interpreter: binary
    source: ./bin/server-macos
  - platform: win32
    interpreter: binary
    source: ./bin/server-win.exe

エンジンのプロパティ

interpreter string (default: node) — blocklet を実行するためのランタイム。有効な値: node、blocklet、binary、bun。
platform string — オプションの OS プラットフォーム。engine が配列の場合に、異なる OS (例: linux、darwin、win32) の設定を指定するために使用します。
source string | object — インタープリタが blocklet の場合のエンジンのソース。URL 文字列、または URL や Blocklet Store を参照するオブジェクトを指定できます。
args string[] (default: []) — 実行可能ファイルに渡すコマンドライン引数の配列。

Docker (docker)

engine プロパティの代替として、docker を使用してコンテナ化された環境で blocklet を実行できます。これは、複雑な依存関係を持つアプリケーションや JavaScript 以外のランタイムに最適です。image または dockerfile のいずれかを提供する必要があります。

ビルド済み Docker イメージの使用

docker:
  image: 'nginx:latest'
  egress: true

dockerfile を使用する場合、そのパスをルートの files 配列に含める必要もあります。

Dockerfile からのビルド

docker:
  dockerfile: 'Dockerfile.prod'
files:
  - 'Dockerfile.prod'

Docker のプロパティ

image string — 使用する Docker イメージの名前。
dockerfile string — イメージをビルドするための Dockerfile へのパス。image と dockerfile を同時に使用することはできません。
egress boolean (default: true) — blocklet が外部ネットワークにアクセスできるかどうか。

ランタイム要件 (requirements)

このオブジェクトは、blocklet が正しく実行されるために必要な環境制約を定義します。システムは、互換性を確保するためにインストール前にこれらの要件をチェックします。

要件の例

requirements:
  server: '>=1.16.0'
  os: '*'
  cpu: 'x64'
  nodejs: '>=18.0.0'

要件のプロパティ

server string — 必要な Blocklet Server バージョンの有効な SemVer 範囲。デフォルトは最新の安定バージョンです。
os string | string[] (default: *) — 互換性のあるオペレーティングシステム。任意の OS の場合は * を使用します。単一の文字列または配列 (例: ['linux', 'darwin']) を指定できます。有効なプラットフォームには aix、darwin、freebsd、linux、openbsd、sunos、win32 が含まれます。
cpu string | string[] (default: *) — 互換性のある CPU アーキテクチャ。任意のアーキテクチャの場合は * を使用します。単一の文字列または配列 (例: ['x64', 'arm64']) を指定できます。有効なアーキテクチャには arm、arm64、ia32、mips、mipsel、ppc、ppc64、s390、s390x、x32、x64 が含まれます。
nodejs string (default: *) — 必要な Node.js バージョンの有効な SemVer 範囲。
fuels array — 特定の操作のために接続されたウォレットで必要な資産 (トークン) のリストを指定します。
aigne boolean — true の場合、blocklet が AI Engine を利用可能にする必要があることを示します。

環境変数 (environments)

environments 配列を使用すると、カスタム設定変数を定義できます。これらは、インストール中または blocklet の設定ページでユーザーに提示され、API キーを安全に入力したり、機能フラグを設定したり、動作をカスタマイズしたりすることができます。

環境変数の定義

environments:
  - name: 'API_KEY'
    description: '外部サービス用の秘密の API キーです。'
    required: true
    secure: true
  - name: 'FEATURE_FLAG_BETA'
    description: 'この blocklet のベータ機能を有効にします。'
    required: false
    default: 'false'
    validation: '^(true|false)$'

キーの命名規則:

名前は予約済みのプレフィックス BLOCKLET_、COMPONENT_、または ABTNODE_ で始まってはいけません。
名前には文字、数字、アンダースコア (_) のみを含めることができます。

環境プロパティ

name string (required) — 環境変数の名前。
description string (required) — この変数が何のためのものかを説明する、ユーザーフレンドリーな説明。
default string — オプションのデフォルト値。secure が true の場合は使用できません。
required boolean (default: false) — ユーザーがこの変数に値を指定する必要があるかどうか。
secure boolean (default: false) — true の場合、値は機密データ (例: パスワード、API キー) として扱われ、暗号化されて保存され、UI で非表示になります。
validation string — ユーザーの入力を検証するためのオプションの正規表現文字列。
shared boolean — true の場合、この変数はコンポーネント間で共有できます。secure が true の場合はデフォルトで false になります。

ライフサイクルスクリプト (scripts)

スクリプトは、blocklet のライフサイクルにフックするシェルコマンドであり、インストール、起動、アンインストールなどの特定の段階で自動タスクを実行できます。次の図は、インストールと起動のフックがいつ実行されるかを示しています:

Execution & Environment

スクリプトフックの例

scripts:
  pre-install: 'npm install --production'
  post-start: 'node ./scripts/post-start.js'
  pre-stop: 'echo "Shutting down..."'

利用可能なフック

フック (`kebab-case`)	いつ実行されるか
`dev`	開発モードで blocklet を実行するためのコマンド。
`e2eDev`	開発環境でエンドツーエンドテストを実行するためのコマンド。
`pre-flight`	インストールプロセスが開始される前、初期チェックのため。
`pre-install`	blocklet ファイルが最終的な宛先にコピーされる前。
`post-install`	blocklet が正常にインストールされた後。
`pre-start`	blocklet のメインプロセスが開始される前。
`post-start`	blocklet が正常に起動した後。
`pre-stop`	blocklet が停止される前。
`pre-uninstall`	blocklet がアンインストールされる前。
`pre-config`	設定ユーザーインターフェースがユーザーに表示される前。

タイムアウト (timeout)

このオブジェクトを使用すると、プロセスが無期限にハングするのを防ぐために、重要なライフサイクル操作の最大待機時間を設定できます。

タイムアウト設定

timeout:
  start: 120  # blocklet が起動するのを最大 120 秒待つ
  script: 600 # スクリプトを最大 10 分間実行できるようにする

タイムアウトのプロパティ

start number (default: 60) — blocklet が起動するのを待つ最大時間 (秒単位)。10 から 600 の間でなければなりません。
script number — 任意のライフサイクルスクリプトが実行される最大時間 (秒単位)。1 から 1800 の間でなければなりません。

実行環境が設定されたら、次のステップは blocklet が外部とどのように通信するかを定義することです。インターフェースとサービスのセクションに進み、Web ページと API エンドポイントを公開する方法を学びましょう。