Bluetooth: requestDevice() メソッド

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。

安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。

Bluetooth.requestDevice()Bluetooth インターフェイスのメソッドで、指定のオプションに合致する BluetoothDevice オブジェクトで履行される Promise を返します。 選択用の UI が無い場合は、このメソッドは基準に合致する最初の機器を返します。

構文

js
requestDevice()
requestDevice(options)

引数

options 省略可

機器の選択に関するオプションを設定するオブジェクトです。 以下のオプションが利用可能です。

filters 省略可

照合する機器のプロパティを示すフィルターオブジェクトの配列です。 フィルターオブジェクトに照合するには、機器はフィルターのすべての値(指定する servicesnamenamePrefix など)に一致しなければなりません。

各フィルターは以下のプロパティを持つオブジェクトの配列で構成されます。

services 省略可

Bluetooth 機器が対応しなければならない Bluetooth GATT (Generic Attribute Profile) サービスを示す値の配列。 それぞれの値は GATT 割り当てられたサービスリストにある有効な名前、例えば 'battery_service''blood_pressure' です。 また、'0000180F-0000-1000-8000-00805f9b34fb' のようなサービスの完全な UUID、または短い 16 ビット (0x180F) または 32 ビットのエイリアスを渡すこともできます。 これらは BluetoothUUID.getService() に渡すことができる値と同じであることに注意してください。

name 省略可

照合する端末の正確な名前を格納した文字列。

namePrefix 省略可

照合する接頭辞を格納した文字列。 この文字列で始まる名前の機器すべてに一致します。

manufacturerData 省略可

Bluetooth Low Energy (BLE) の広告パケットの製造元データと照合するオブジェクトの配列。 それぞれのフィルターオブジェクトには以下のプロパティがあります。

companyIdentifier

必須で端末の製造元を識別する番号。 会社識別子は、Bluetooth 仕様書の割り当て番号の第 7 節に掲載されています。 例えば、"Digianswer A/S" によって製造され、割り当てられた 16 進数が 0x000C である端末と照合するには、12 を指定します。

dataPrefix 省略可

データの接頭辞。 製造者データの広告の先頭にある値と照合する値を格納するバッファー。

mask 省略可

これにより、サービスデータの dataPrefix の一部のバイトをマスクすることで、製造者データ内の一部のバイトに対して照合することができます。

serviceData 省略可

Bluetooth Low Energy (BLE) の広告パケット内のサービスデータと照合するオブジェクトの配列。 それぞれのフィルターオブジェクトには以下のプロパティがあります。

service

GATT サービス名、サービス UUID、または UUID 16 ビットまたは 32 ビットフォーム。 これは services 配列の要素と同じ値を取ります。

dataPrefix 省略可

データの接頭辞。 サービスデータの広告の先頭にある値と照合する値を格納するバッファー。

mask 省略可

これにより、サービスデータの dataPrefix の一部のバイトをマスクして、サービスデータ内の一部のバイトに対して照合することができます。

exclusionFilters 省略可

照合から除外する端末の特性を示すフィルターオブジェクトの配列。 配列要素のプロパティは filters と同じです。

optionalServices 省略可

オプションのサービス識別子の配列。

識別子は services 配列の要素(GATT サービス名、サービスワーカースクリプト (service UUID)、UUID short 16-bit または 32-bit form)と同じ値を導きます。

optionalManufacturerData 省略可

オプションで、整数による製造者コードの配列。 これは companyIdentifier と同じ値を取ります。

このデータは機器のフィルタリングには使用しませんが、指定した設定に一致する広告は advertisementreceived イベントで配信されます。 これは、許可プロンプトでユーザーに表示する機器を制御するフィルターに制約されることなく、Bluetooth 機器から受信したデータへの関心をコードで指定することができるので便利です。

acceptAllDevices 省略可

リクエストされたスクリプトがすべての Bluetooth 端末を受け入れることができることを示す論理値。 既定値は false です。

このオプションは、機器がフィルタリングに有益な情報が十分に広告されていない場合に適しています。 acceptAllDevicestrue に設定した場合、filtersexclusionFilters をすべて除外し、optionalServices を設定しなければ、返された端末を使用することができません。

ユーザーが現在のオリジンでペアリングする端末を選択した後、filters.services または optionalServices のいずれかの要素のサービスリストに UUID が掲載されているサービスにのみアクセスすることができます。 そのため、要求されるサービスをリストアップすることが重要です。 具体的な例としては、name だけでフィルターをかける場合は、optionalServices で必要なサービスを指定する必要があります。

メモ: たとえ options 引数が技術的にはオプションであっても、結果を返すためには filters に値を設定するか、acceptAllDevicestrue を設定する必要があります。

返値

BluetoothDevice オブジェクトで解決する Promise を返します。

例外

TypeError

指定された options が意味をなさないとき発生します。 たとえば、options.filters が存在して、かつ options.acceptAllDevicestrue に設定されている場合や、options.filters が存在せず、かつ options.acceptAllDevicesfalse に設定されている場合に発生します。 options.filters[] に設定されている場合も発生します。

NotFoundError DOMException

指定のオプションに合致する Bluetooth 機器が存在しないとき発生します。

SecurityError DOMException

安全でないオリジンで呼び出されたときなど、現在のコンテキストでセキュリティの懸念によりこの操作が許可されないとき発生します。

js
// 以下の広告をしている機器にマッチする検索オプションを使用します。
// ・標準の心拍数サービス
// ・16 ビットのサービス ID が 0x1802 と 0x1803
// ・プロプライエタリーの 128 ビット UUID c48e6067-5295-48d3-8d5c-0395f61792b1 を持つサービス
// ・名前 "ExampleName" を持つ機器
// ・名前が "Prefix" で始まる機器
//
// そして、機器が該当のサービスを広告していない場合でも、
// 機器に存在すれば、バッテリーサービスへのアクセスを有効化します。
let options = {
  filters: [
    { services: ["heart_rate"] },
    { services: [0x1802, 0x1803] },
    { services: ["c48e6067-5295-48d3-8d5c-0395f61792b1"] },
    { name: "ExampleName" },
    { namePrefix: "Prefix" },
  ],
  optionalServices: ["battery_service"],
};

navigator.bluetooth
  .requestDevice(options)
  .then((device) => {
    console.log(`名前: ${device.name}`);
    // 機器に何かをする
  })
  .catch((error) => console.error(`何かがうまくいきませんでした。 ${error}`));

詳細な例が仕様書にあります。

仕様書

Specification
Web Bluetooth
# dom-bluetooth-requestdevice

ブラウザーの互換性

BCD tables only load in the browser

関連情報