service

Since v8.0.75

serviceモジュールは、JSHアプリケーションからサービスコントローラーのJSON-RPC APIを呼び出すクライアントモジュールです。

一般的な使用方法は以下のとおりです。

const service = require('service');

サービスコントローラーのアドレスは、通常はシェルやセッションが設定したSERVICE_CONTROLLER環境変数から取得します。

コントローラーは実行ごとにランダムなアドレスで待ち受ける場合があるため、通常はアドレスをハードコードしません。別のコントローラーアドレスが既知の場合や、明示的に別のコントローラーへ接続する必要がある場合にのみ、options.controllerを使用します。

Client

Clientは、サービスコントローラーと通信する基本クライアント型です。

再利用するクライアントインスタンスが必要な場合は、new service.Client(...)を使用してください。

構文

new Client([options])

オプション

オプション	型	既定値	説明
controller	String		明示的に使用するコントローラーアドレス。省略すると`SERVICE_CONTROLLER`環境変数を使用します。
timeout	Number	`5000`	RPCのタイムアウト（ミリ秒）。コールバック方式のリクエストが完了またはタイムアウトするまで、その寿命を維持するためにも同じ値を使用します。

controllerには、固定の既定アドレスはありません。 SERVICE_CONTROLLERがなく、options.controllerも指定しない場合、クライアントの作成は失敗します。

使用例

1
2
const service = require('service');
const client = new service.Client({ timeout: 1000 });

上記の例は、SERVICE_CONTROLLER環境変数が設定済みであることを前提とします。

明示的に別のコントローラーアドレスを使用する場合にのみ、以下のようにcontrollerを指定します。

1
2
3
4
5
const service = require('service');
const client = new service.Client({
    controller: 'unix:///tmp/example-service-controller.sock',
    timeout: 1000,
});

主なプロパティ

controller
timeout
runtime
details

Client メソッド

call(method[, params], callback)
status([name], callback)
read(callback)
update(callback)
reload(callback)
install(config, callback)
uninstall(name, callback)
start(name, callback)
stop(name, callback)

使用例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const service = require('service');
const client = new service.Client();

client.status((err, services) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println('count=', services.length);
});

call()

任意のサービスコントローラーRPCメソッドを直接呼び出します。

構文

client.call(method[, params], callback)

使用例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const service = require('service');
const client = new service.Client();

client.call('service.list', null, (err, result) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println(result.length);
});

status()

現在のサービス状態を取得します。

nameを省略すると、サービス一覧のスナップショットを返します。
nameを指定すると、単一サービスのスナップショットを返します。
このメソッドは、servicectl status [service_name]コマンドの形式に対応しています。

構文

client.status([name], callback)

使用例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
const service = require('service');
const client = new service.Client();

client.status((err, services) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println('count=', services.length);
});

client.status('alpha', (err, snapshot) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println(snapshot.status);
});

read()

サービス設定ディレクトリを再読み込みし、最新の再読み込みスナップショットを返します。

構文

client.read(callback)

update()

現在の再読み込みスナップショットを適用し、更新結果を返します。

update()は、現在の再読み込み結果に含まれる差分だけを適用します。
再読み込み結果の影響を受けるサービスだけを、停止・開始・追加・削除します。

構文

client.update(callback)

reload()

設定を再読み込みし、その結果を直ちに適用します。

reload()はupdate()と異なり、現在実行中のすべてのサービスを先に停止します。
その後、現在の設定でenableになっているサービスだけを再起動します。
そのため、reload()前に実行中だったサービスでも、現在の設定でenableでなければ再起動しません。

構文

client.reload(callback)

install()

設定オブジェクトからサービスをインストールし、そのサービスのスナップショットを返します。

構文

client.install(config, callback)

使用例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
const service = require('service');
const client = new service.Client();

client.install({
    name: 'alpha',
    enable: false,
    executable: 'echo',
    args: ['hello'],
}, (err, snapshot) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println(snapshot.config.name, snapshot.status);
});

uninstall()

サービスを削除し、成功時にtrueを返します。

構文

client.uninstall(name, callback)

start()

サービスを開始し、更新したサービスのスナップショットを返します。

構文

client.start(name, callback)

stop()

サービスを停止し、更新したサービスのスナップショットを返します。

構文

client.stop(name, callback)

runtime.get()

サービスのランタイムスナップショットを取得します。

戻り値には、outputとdetailsが含まれます。

構文

client.runtime.get(name, callback)

使用例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const service = require('service');
const client = new service.Client();

client.runtime.get('alpha', (err, runtime) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println(JSON.stringify(runtime.details || {}));
});

details.get()

サービスのdetail値を取得します。

keyを省略すると、details全体のスナップショットを返します。
keyを指定し、そのキーがない場合は、エラーを返します。

構文

client.details.get(name[, key], callback)

使用例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const service = require('service');
const client = new service.Client();

client.details.get('alpha', 'health', (err, runtime) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println(runtime.details.health);
});

details.add()

新しいdetailのキーと値を追加します。

同じキーが存在する場合は、エラーを返します。

構文

client.details.add(name, key, value, callback)

details.update()

既存のdetailのキーと値を更新します。

キーが存在しない場合は、エラーを返します。

構文

client.details.update(name, key, value, callback)

details.set()

detailのキーと値を設定します。

キーがなければ作成し、あれば上書きします。

構文

client.details.set(name, key, value, callback)

使用例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const service = require('service');
const client = new service.Client();

client.details.set('alpha', 'health', 'ok', (err, runtime) => {
    if (err) {
        console.println(err.message);
        return;
    }
    console.println(runtime.details.health);
});

details.delete()

detailのキーを削除します。

キーがない場合は、エラーを返します。

構文

client.details.delete(name, key, callback)

resolveController()

コントローラーのアドレスを決定します。

引数を渡すと、その値を使用します。
引数がなければ、SERVICE_CONTROLLER環境変数を参照します。

構文

resolveController([value])

動作例

1
2
3
const service = require('service');
console.println(service.resolveController());
console.println(service.resolveController('unix:///tmp/example-service-controller.sock'));

動作に関する注意

すべてのAPIはコールバック方式の非同期形式です。
コントローラーへの接続失敗、タイムアウト、RPCエラーは、コールバックの第1引数に渡されます。
サービスRPCの処理中は、短いトップレベルスクリプトがコールバック前に終了しないように、モジュールが内部でリクエストの寿命を維持します。
このkeepalive期間は、実際のtimeout値に従い、リクエストが成功・失敗・タイムアウトのいずれかで完了すると直ちに解放されます。
new Client()は、options.controllerを省略すると、既定でSERVICE_CONTROLLERを使用します。

最終更新日 9月 10, 2026

semver vizspec