ネイティブメッセージング

[アーティクル]
01/19/2024

ユーザーのデバイスにインストールされているネイティブ Win32 アプリと通信するために、拡張機能では、他のメッセージ渡し API と同様の API が使用されます。ネイティブアプリホストは、標準入力と標準出力を使用して、拡張機能を含むメッセージを送受信します。

ネイティブメッセージングを使用する拡張機能は、他の拡張機能と同様に Microsoft Edge にインストールされます。ただし、ネイティブアプリは Microsoft Edge によってインストールまたは管理されません。

拡張機能とネイティブアプリホストを取得するには、次の 2 つの異なる配布モデルがあります。

拡張機能とホストをパッケージ化します。ユーザーがパッケージをインストールすると、拡張機能とホストの両方がインストールされます。
または、 Microsoft Edge アドオン Web サイトを使用して拡張機能をインストールすると、ユーザーにホストのインストールを求めるメッセージが表示されます。

ネイティブアプリホストでメッセージを送受信する拡張機能を作成するには、次の手順を実行します。

手順 1: 拡張機能マニフェストにアクセス許可を追加する

拡張機能の nativeMessagingmanifest.json ファイルにアクセス許可を追加します。

これは 拡張マニフェストファイルであり、 ネイティブメッセージングホストマニフェストファイルではありません。これについては、後のセクションで説明します。

manifest.json ファイルの例を次に示します。

マニフェスト V3
マニフェスト V2

{
    "name": "Native Messaging Example",
    "version": "1.0",
    "manifest_version": 3,
    "description": "Send a message to a native app.",
    "app": {
        "launch": {
            "local_path": "main.html"
        }
    },
    "icons": {
        "128": "icon-128.png"
    },
    "permissions": ["nativeMessaging"]
}

{
    "name": "Native Messaging Example",
    "version": "1.0",
    "manifest_version": 2,
    "description": "Send a message to a native app.",
    "app": {
        "launch": {
            "local_path": "main.html"
        }
    },
    "icons": {
        "128": "icon-128.png"
    },
    "permissions": ["nativeMessaging"]
}

手順 2: ネイティブメッセージングホストマニフェストファイルを作成する

ネイティブアプリは、ネイティブメッセージングホストマニフェストファイルを提供する必要があります。ネイティブメッセージングホストマニフェストファイルには、次の情報が含まれています。

ネイティブメッセージングホストランタイムへのパス。
拡張機能との通信方法。
通信先の許可される拡張機能の一覧。

ブラウザーは、ネイティブメッセージングホストマニフェストを読み取り、検証します。ブラウザーは、ネイティブメッセージングホストマニフェストファイルをインストールまたは管理しません。

ネイティブメッセージングホストマニフェストファイルは、Microsoft Edge 拡張機能の一部であるマニフェスト V3 または V2 ファイルとは異なります。

ネイティブメッセージングホストマニフェストファイルの例:

{
    "name": "com.my_company.my_app",
    "description": "My App",
    "path": "C:\\Program Files\\My App\\chrome_native_messaging_host.exe",
    "type": "stdio",
    "allowed_origins": [
        "chrome-extension://knldjmfmopnpolahpmmgbagdohdnhkik/"
    ]
}

ネイティブメッセージングホストマニフェストファイルは、次のキーを含む有効な JSON ファイルである必要があります。

キー	詳細
`name`	ネイティブメッセージングホストの名前を指定します。クライアントは、または `runtime.sendNativeMessage`に文字列を`runtime.connectNative`渡します。値には、小文字の英数字、アンダースコア、ドットのみを含める必要があります。値はドット (ピリオド) で開始または終了することはできません。また、ドットの後に別のドットを付けてはいけません。
`description`	アプリについて説明します。
`path`	ネイティブメッセージングホストバイナリへのパスを指定します。 Windows デバイスでは、ネイティブメッセージングホストマニフェストファイルを含むディレクトリへの相対パスを使用できます。 macOS と Linux では、パスは絶対パスである必要があります。ホストプロセスは、現在のディレクトリがホストバイナリを含むディレクトリに設定された状態で開始されます。たとえば (Windows) では、パラメーターがに `C:\App\nm_host.exe`設定されている場合、バイナリは現在のディレクトリ (`C:\App\`) を使用して開始されます。
`type`	ネイティブメッセージングホストとの通信に使用するインターフェイスの種類を指定します。この値は、ホストと通信するためにと `stdout` を使用`stdin`するように Microsoft Edge に指示します。許容される値は `stdio`のみです。
`allowed_origins`	ネイティブメッセージングホストにアクセスできる拡張機能の一覧を指定します。拡張機能を識別して通信するようにアプリを有効にするには、ネイティブメッセージングホストマニフェストファイルで次の値を設定します。 `"allowed_origins": ["chrome-extension://{microsoft_catalog_extension_id}"]`

拡張機能をサイドロードして、ホストでネイティブメッセージングをテストします。開発中に拡張機能をサイドロードして取得 microsoft_catalog_extension_idするには:

に edge://extensions移動し、[ 開発者モード ] トグルボタンをオンにします。
[ 開梱された読み込み] を選択し、サイドロードする拡張機能パッケージを選択します。
[OK] をクリックします。
ページに edge://extensions 移動し、拡張機能が一覧表示されていることを確認します。
ページの microsoft_catalog_extension_id 拡張機能の一覧からキー (ID) をコピーします。

拡張機能をユーザーに配布する準備ができたら、Microsoft Edge アドオン Web サイトに拡張機能を発行します。公開された拡張機能の拡張機能 ID は、拡張機能のサイドローディング中に使用される ID とは異なる場合があります。 ID が変更された場合は、公開されている拡張機能の ID を使用してネイティブメッセージングホストマニフェストファイルで更新 allowed_origins します。

手順 3: ネイティブメッセージングホストマニフェストファイルをシステムにコピーする

最後の手順では、ネイティブメッセージングホストマニフェストファイルをコンピューターにコピーし、このマニフェストファイルが正しく構成されていることを確認します。ネイティブメッセージングホストマニフェストファイルが想定される場所に配置されるようにするには、次の手順を実行します。場所はプラットフォームによって異なります。

Linux と macOS の場合:

ネイティブメッセージングホストマニフェストファイルに対する 読み取り アクセス許可を必ず指定してください。
ホストランタイムに対する実行アクセス許可を必ず指定してください。

ネイティブメッセージングホストマニフェストファイルは、ファイルシステム内の任意の場所に配置できます。アプリインストーラーはレジストリキーを作成し、キーの既定値をネイティブメッセージングホストマニフェストファイルの完全パスに設定する必要があります。

レジストリキーの例を次に示します。

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app

マニフェストキーを使用してレジストリキーをディレクトリに追加するには、次のいずれかの操作を行います。

コマンドプロンプトでコマンドを実行します。

REG ADD "HKCU\Software\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f

または、次のようにファイルを .reg 作成して実行します。
1. 次のコマンドをファイルに .reg コピーします。
```
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Microsoft\Edge\NativeMessagingHosts\com.my_company.my_app]
@="C:\\path\\to\\nmh-manifest.json"
```
2. ファイルを実行します .reg 。作成した .reg ファイルをバッチスクリプトの一部として実行する場合は、管理者コマンドプロンプトを使用して実行してください。

Microsoft Edge では、ルートキーに HKEY_CURRENT_USER 続いてを照会します HKEY_LOCAL_MACHINE。どちらのキーでも、最初に 32 ビットレジストリが検索され、次にネイティブメッセージングホストを識別するために 64 ビットレジストリが検索されます。レジストリキーは、ネイティブメッセージングホストマニフェストファイルの場所を指定します。

Microsoft Edge のレジストリエントリにネイティブメッセージングホストマニフェストファイルの場所がない場合は、Chromiumと Chrome のレジストリの場所がフォールバックオプションとして使用されます。

Microsoft Edge は、以前に一覧表示された場所のいずれかでレジストリキーを見つけた場合、次のコードスニペットに記載されている場所に対してクエリを実行しません。

レジストリの場所の検索順序は次のとおりです。

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Chromium\NativeMessagingHosts\
HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\

HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Edge\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Chromium\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Google\Chrome\NativeMessagingHosts\

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Edge\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Chromium\NativeMessagingHosts\
HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\

WOW6432Node レジストリノード

HKEY_CURRENT_USER\SOFTWARE\WOW6432Nodeレジストリノードは、64 ビットコンピューターでは検索されません。これは、レジストリの動作方法が原因です。詳細については、「 Windows 上の Windows を含む Windows インストールの影響を受けるレジストリキー (WOW) による複数のプロセッサアーキテクチャのサポート」を参照してください。

両方のストアに必要な拡張 ID

Microsoft Edge アドオンと Chrome Web ストアに拡張機能がある場合は、ネイティブメッセージングホストマニフェストファイルの両方のストア allowed_origins に対応する拡張機能 ID を追加する必要があります。最初に見つかったレジストリの場所に対応するネイティブメッセージングホストマニフェストファイルのみが読み取られるので、これは必須です。

ネイティブメッセージングホストマニフェストファイルを格納するには:

すべてのユーザーが使用できるシステム全体のネイティブメッセージングホストは、固定の場所に格納されます。たとえば、ネイティブメッセージングホストマニフェストファイルは、次の場所に格納する必要があります。
```
/Library/Microsoft/Edge/NativeMessagingHosts/com.my_company.my_app.json
```
現在のユーザーのみが使用できるユーザー固有のネイティブメッセージングホストは、ユーザーデータディレクトリのNativeMessagingHostsサブディレクトリにあります。たとえば、ネイティブメッセージングホストマニフェストファイルは、次の場所に格納する必要があります。
```
~/Library/Application Support/Microsoft Edge {Channel_Name}/NativeMessagingHosts/com.my_company.my_app.json
```
は{Channel_Name}Microsoft Edge {Channel_Name}、次のいずれかの値である必要があります。
- Canary
- Dev
- Beta
安定チャネルを使用する場合は、 {Channel_Name} 必須ではありません。

ネイティブメッセージングホストマニフェストファイルを格納するには:

すべてのユーザーが使用できるシステム全体のネイティブメッセージングホストは、固定の場所に格納されます。ネイティブメッセージングホストマニフェストファイルは、次の場所に格納する必要があります。
```
/etc/opt/edge/native-messaging-hosts
```
現在のユーザーのみが使用できるユーザー固有のネイティブメッセージングホストは、ユーザーデータディレクトリのNativeMessagingHostsサブディレクトリにあります。ネイティブメッセージングホストマニフェストファイルは、次の場所に格納する必要があります。
```
~/.config/microsoft-edge/NativeMessagingHosts
```

ネイティブメッセージングプロトコル

Microsoft Edge は、各ネイティブメッセージングホストを個別のプロセスで開始し、標準入力 () と標準出力 (stdinstdout) を使用して通信します。メッセージを双方向に送信するには、同じ形式が使用されます。各メッセージは、UTF-8 でエンコードされた JSON を使用してシリアル化され、ネイティブバイト順に 32 ビットのメッセージ長が先行します。ネイティブメッセージングホストからの 1 つのメッセージの最大サイズは 1 MB です。主に、Microsoft Edge がネイティブアプリケーションを誤って動作しないように保護します。ネイティブメッセージングホストに送信されるメッセージの最大サイズは 4 GB です。

ネイティブメッセージングホストの最初の引数は、呼び出し元 (通常 chrome-extension://[ID of allowed extension]は ) です。これにより、ネイティブメッセージングホストマニフェストのキーに allowed_origins 複数の拡張機能が指定されている場合に、ネイティブメッセージングホストはメッセージのソースを識別できます。上記の「手順 2: ネイティブメッセージングホストマニフェストファイルを作成する」を参照してください。

Windows では、ネイティブメッセージングホストには、呼び出し元の Microsoft Edge ネイティブウィンドウへのハンドルを持つコマンドライン引数も渡されます。 --parent-window=<decimal handle value> これにより、ネイティブメッセージングホストは、正しく親であるネイティブ UI ウィンドウを作成できます。呼び出し元のコンテキストがサービスワーカーの場合、この値は 0 になります。

を使用 runtime.connectNativeしてメッセージングポートを作成すると、Microsoft Edge はネイティブメッセージングホストプロセスを開始し、ポートが破棄されるまで実行し続けます。一方、メッセージングポートを作成せずにを使用 runtime.sendNativeMessageしてメッセージが送信されると、Microsoft Edge はメッセージごとに新しいネイティブメッセージングホストプロセスを開始します。その場合、ホストプロセスによって生成された最初のメッセージは元の要求への応答として処理され、Microsoft Edge は、呼び出されたときに runtime.sendNativeMessage 指定された応答コールバックに渡します。その場合、ネイティブメッセージングホストによって生成されたその他のすべてのメッセージは無視されます。

ネイティブアプリケーションへの接続

ネイティブアプリケーションとの間でメッセージを送受信することは、クロス拡張機能メッセージングとよく似ています。メイン違いは、 runtime.connectNative ではなくを使用しruntime.sendNativeMessage、ではなく runtime.connectを使用runtime.sendMessageすることです。

これらのメソッドを使用するには、拡張機能の nativeMessaging マニフェストファイルでアクセス許可を宣言する必要があります。上記の「手順 1: 拡張機能マニフェストにアクセス許可を追加する」を参照してください。

これらのメソッドは、拡張機能のページとサービスワーカー内でのみ、コンテンツスクリプト内では使用できません。コンテンツスクリプトからネイティブアプリケーションに通信する場合は、メッセージをサービスワーカーに送信してネイティブアプリケーションに渡します。

次の例では、 runtime.Port ネイティブメッセージングホスト com.my_company.my_applicationに接続されているオブジェクトを作成し、そのポートからのメッセージのリッスンを開始し、1 つの送信メッセージを送信します。

var port = chrome.runtime.connectNative('com.my_company.my_application');
port.onMessage.addListener(function (msg) {
  console.log('Received' + msg);
});
port.onDisconnect.addListener(function () {
  console.log('Disconnected');
});
port.postMessage({text: 'Hello, my_application'});

を使用して runtime.sendNativeMessage 、ポートを作成せずにネイティブアプリケーションにメッセージを送信します。例:

chrome.runtime.sendNativeMessage(
  'com.my_company.my_application',
  {text: 'Hello'},
  function (response) {
    console.log('Received ' + response);
  }
);

ネイティブメッセージングのデバッグ

特定のネイティブメッセージングエラーが発生すると、Microsoft Edge のエラーログに出力が書き込まれます。これには、ネイティブメッセージングホストの起動に失敗した場合、通信プロトコルへの stderr 書き込み、または通信プロトコルへの違反が含まれます。 Linux および macOS では、コマンドラインから Microsoft Edge を起動し、ターミナルでその出力を監視することで、このログに簡単にアクセスできます。 Windows では、「ログ記録を有効にする方法」で説明されているようにを使用--enable-loggingします。

それらを解決するための一般的なエラーとヒントを次に示します。

ネイティブメッセージングホストを開始できませんでした。

ネイティブメッセージングホストファイルを実行するための十分なアクセス許可があるかどうかを確認します。

指定されたネイティブメッセージングホスト名が無効です。

名前に無効な文字が含まれているかどうかを確認します。小文字の英数字、アンダースコア、ドット (ピリオド) のみを使用できます。名前をドットで始めたり終えたりすることはできません。また、ドットの後に別のドットを付けることはできません。

ネイティブホストが終了しました。

ネイティブメッセージングホストへのパイプは、Microsoft Edge がメッセージを読み取る前に破損していました。これは、ネイティブメッセージングホストから開始される可能性が最も高いです。

指定されたネイティブメッセージングホストが見つかりません。

以下のことを確認してください。

拡張子とマニフェストファイルで名前のスペルが正しいかどうか。
マニフェストは適切なディレクトリにあり、正しい名前ですか? 想定される形式については、「ネイティブメッセージングホストの場所」を参照してください。
マニフェストファイルの形式は正しいですか? 特に、JSON は有効で整形式であり、値は、上記の手順 2: ネイティブメッセージングホストマニフェスト ファイルの作成に従って、ネイティブメッセージングホストマニフェストの定義と一致しますか?
で指定されたファイルは path 存在しますか? Windows の場合、パスは相対パスである可能性がありますが、macOS と Linux では、パスは絶対パスである必要があります。

ネイティブメッセージングホスト ホスト名 が登録されていません。 (Windows のみ)

ネイティブメッセージングホストが Windows レジストリに見つかりませんでした。キーが実際に作成され、ネイティブメッセージングホストの場所で説明されているように、必要な形式と一致するかどうかを使用regeditしてダブルチェックします。

指定されたネイティブメッセージングホストへのアクセスは禁止されています。

拡張機能の配信元はに表示されますか allowed_origins?

ネイティブメッセージングホストとの通信中にエラーが発生しました。

これは、ネイティブメッセージングホストでの通信プロトコルの不適切な実装を示します。

のすべての stdout 出力がネイティブメッセージングプロトコルに準拠していることを確認します。デバッグ目的でデータを印刷する場合は、に stderr書き込みます。
32 ビットメッセージの長さがプラットフォームのネイティブ整数形式 (リトルエンディアンまたはビッグエンディアン) であることを確認します。
メッセージの長さは 1024*1024 を超えてはなりません。
メッセージサイズは、メッセージ内のバイト数と同じである必要があります。文字は複数のバイトで表される可能性があるため、これは文字列の "長さ" とは異なる場合があります。
Windows 専用: プログラムの I/O モードがに O_BINARY設定されていることを確認します。既定では、I/O モードはです。これは、改行 () が O_TEXTWindows スタイルの行の終わり (\r\n0D 0A\n = 0A = ) に置き換えられるとメッセージ形式が破損します。 I/O モードは、を使用 __setmodeして設定できます。

注:

このページの一部は、 Google によって作成および共有され、クリエイティブ・コモンズ属性 4.0 国際ライセンスに記載されている条件に従って使用される作業に基づく変更です。元のページはこちらにあります。

この作品は、クリエイティブ・コモンズ属性4.0国際ライセンスに基づきライセンスされています。

ネイティブ メッセージング

手順 1: 拡張機能マニフェストにアクセス許可を追加する

手順 2: ネイティブ メッセージング ホスト マニフェスト ファイルを作成する

手順 3: ネイティブ メッセージング ホスト マニフェスト ファイルをシステムにコピーする

WOW6432Node レジストリ ノード

両方のストアに必要な拡張 ID

ネイティブ メッセージング プロトコル

ネイティブ アプリケーションへの接続

ネイティブ メッセージングのデバッグ

その他のリソース