ハンドルはインスタンスを弱く参照し、そのライフタイムを延長しません。

```lua
local target = Instance.new("Part")
target.Name = "TargetPart"

local handle = InstanceHandle.new(target)
local empty = InstanceHandle.new(nil)

print(handle:Get()) --> TargetPart
print(empty:Get()) --> nil
```

`instance` が `Class.Instance` でも `nil` でもない場合は例外をスローします。


InstanceHandle.new

instance

参照するインスタンス、または空のハンドルの場合は `nil`。


指定された `Class.Instance` を参照する新しい `Datatype.InstanceHandle` を返します。


`Datatype.InstanceHandle` データ型は、ローカルで利用できない可能性のある `Class.Instance` への弱い参照です。まだ到着していないインスタンス、ストリーミングアウトする可能性のあるインスタンス、または別のマシンにのみ存在するインスタンスを指し示すために使用し、インスタンスがそこに到着したときにそれを取得します。

ハンドルは常に同じターゲットを参照します。そのターゲットに到達するには、`Datatype.InstanceHandle:Wait()` を呼び出します。これは、インスタンスが利用可能になるまで待機します：

```lua
local Workspace = game:GetService("Workspace")

local part = Instance.new("Part")
local target = Instance.new("Part")
target.Name = "TargetPart"
part.Parent = Workspace
target.Parent = Workspace

part:SetAttribute("Target", target)

local handle = part:GetAttribute("Target")
local instance = handle:Wait(10)
if instance then
	print("ターゲットは", instance.Name) --> ターゲットは TargetPart
end
```
インスタンスが表示されるとすぐにコードが実行されるように、タイムアウト付きで `Datatype.InstanceHandle:Wait()` を使用することをお勧めします。すぐに答えが必要で、`nil` を処理できる場合は、毎フレーム実行されるコード内で `Datatype.InstanceHandle:Get()` を使用します。

#### 例

##### 属性

属性は、通常のインスタンス参照の代わりに `Datatype.InstanceHandle` を使用します。ハンドル自体は決して `nil` にならないため、インスタンスが現在存在しない属性と欠落している属性を区別できます：

```lua
local part = Instance.new("Part")

print(part:GetAttribute("Target")) --> nil

part:SetAttribute("Target", InstanceHandle.new(nil))
local handle = part:GetAttribute("Target")
print(handle:Get()) --> nil
```

`Datatype.InstanceHandle` 属性は、`Class.Instance:GetAttributes()` にも表示され、`nil` 値を保持できません。

`Class.Instance:GetAttributeChangedSignal()` は、属性が新しいターゲットに設定されたり削除されたりしたときに発火します。ターゲットがストリーミングインまたはストリーミングアウトしたとき、またはターゲットが破壊されたときには発火しません。利用可能性に反応するには、信号を `Datatype.InstanceHandle:Wait()` と組み合わせます：

```lua
local part = Instance.new("Part")

part:GetAttributeChangedSignal("Target"):Connect(function()
	local handle = part:GetAttribute("Target")
	if not handle then
		return
	end

	local instance = handle:Wait(10)
	if instance then
		print("新しいターゲット:", instance.Name)
	end
end)
```

##### リモートイベント

`Class.RemoteEvent` を通じてハンドルを渡すことで、受信者にまだ持っていないインスタンスへの参照を提供します。受信者は、何も受け取らずにインスタンスを待機します。

サーバースクリプト内で、この関数をリモートイベント、受信プレイヤー、および送信するモデルで呼び出します：

```lua
local function sendHandle(remoteEvent: RemoteEvent, player: Player, spawnedModel: Model)
	local handle = InstanceHandle.new(spawnedModel)
	remoteEvent:FireClient(player, handle)
end
```
クライアントスクリプト内で、同じリモートイベントを使用して、サーバーがハンドルを送信する前にリスニングを開始します：

```lua
local function receiveHandles(remoteEvent: RemoteEvent)
	remoteEvent.OnClientEvent:Connect(function(handle)
		local model = handle:Wait(10)
		if model then
			print("受信しました", model.Name)
		end
	end)
end
```

#### 所有権

ハンドルは弱い参照として機能します。ターゲットを生かし続けることはありません。ターゲットのライフタイムは、あなたの体験の残りの部分によって制御されます：その親と、ガーベジコレクションを防ぐためにスクリプトが保持する通常の参照です。

`Datatype.InstanceHandle:Get()` と `Datatype.InstanceHandle:Wait()` は、インスタンスを保持している限り、通常のインスタンス参照を返します。

ハンドルはそれ以外は軽量で、クリーンアップは必要ありません。

#### 等価性

2つのハンドルは、同じターゲットを参照している場合に等しいです。たとえ別々に作成した場合でも、ターゲットが消えた後でも同様です。すべての空のハンドルは互いに等しいです。それぞれのハンドルは依然として異なる値です。

```lua
local instance1 = Instance.new("Part")
local instance2 = Instance.new("Part")

local a = InstanceHandle.new(instance1)
local b = InstanceHandle.new(instance1)
local c = InstanceHandle.new(instance2)

print(a == b) --> true
print(a == c) --> false
```
等価性はターゲットの同一性に依存するため、ターゲットが現在利用できない場合でも機能します。


このメソッドは待機しません。

`Get()` は、ハンドルが空である場合、ターゲットがスクリプトを実行しているクライアントまたはサーバーに到着していない場合、ターゲットがストリーミングアウトした後にもはや利用できない場合、ターゲットがガーベジコレクションされた場合、またはターゲットが呼び出しスクリプトにアクセスできない場合に `nil` を返します。ターゲットが到着するまで待機するには、`Datatype.InstanceHandle:Wait()` を使用します。


InstanceHandle:Get

参照されたインスタンス、またはローカルで利用できない場合は `nil`。


参照された `Class.Instance` がローカルで利用可能な場合は返し、そうでない場合は `nil` を返します。


ハンドルが空の場合、ターゲットが呼び出しスクリプトにアクセスできない場合、または `timeout` が先に経過した場合は `nil` を返します。ターゲットがすでに利用可能で、ハンドルが空の場合は、`Wait()` はすぐに返ります。

ターゲットが呼び出し元に到達することを保証できない場合は、タイムアウトを渡します。レプリケートされる前に破壊されたターゲットは、解決されないハンドルを残し、タイムアウトなしの `Wait()` は決して返しません。保留中の待機はキャンセルできません：`Library.task.cancel()` はコルーチンを停止しますが、待機はターゲットが到着するかタイムアウトが経過するまで登録解除されません。

`timeout` はゼロより大きい数値でなければなりません。`timeout` がゼロ、負、または数値でない場合は例外をスローします。


InstanceHandle:Wait

timeout

待機する時間（秒）。ゼロより大きくなければなりません。省略すると無限に待機します。


参照されたインスタンス、またはハンドルが空の場合、ターゲットが呼び出しスクリプトにアクセスできない場合、または `timeout` が先に経過した場合は `nil`。


参照された `Class.Instance` がローカルで利用可能になるまで待機し、その後それを返します。


InstanceHandle

ローカルで利用できない可能性のある `Class.Instance` への軽量の弱い参照です。


/reference/engine/datatypes/InstanceHandle.yaml

インスタンスのコンストラクタを保持します。

Data Type

Instance

特定の事象が発生した際に接続された関数を実行するオブジェクトです。

RBXScriptSignal

Luau

number

Learning hub

バーチャル空間

Avatar

アセット

サンプルとプロジェクト

エンジン API

オープンクラウド API

Studio

解析

プラットフォーム

チュートリアル

クリエータープログラム

学習

学ぶ

このメソッドは非同期で、操作の現在の状態を表す `Operation` を返します。このメソッドにはエンドポイントパスが含まれており、これをポーリングすることで実際の応答と該当するメタデータを取得することができます。長時間実行オペレーションについて詳しくは、[ドキュメンテーション]({longRunningOperationsLink})  を参照してください。
            
以下のセクションでは、操作が完了したときに提供される応答とメタデータオブジェクトについて説明します。

ベータエンドポイントが一般向けに使用できるようになりました。破壊的変更は可能ですがまれです。

これらのOpen Cloudドキュメンテーションページは2026年3月31日に削除され、その時点で、新しいOpen Cloudドキュメンテーションに自動的にリダイレクトされます。{linkStart}もっと詳しく{linkEnd}

これらの古いOpen Cloudページは2026年3月31日に削除され、リダイレクトされます。{linkStart}もっと詳しく{linkEnd}

実験的なエンドポイントは公開に向けて準備ができていますが、APIコントラクトが確定するにつれて、時折重大な変更が発生する可能性があります。

このエンドポイントは、APIキーを使って{httpServiceLinkStart}HttpService{httpServiceLinkEnd}を介してバーチャル空間内で呼び出すことができます。

このフィールドはリソースの作成時に設定できますがその後のリクエストでは変更することはできません。

この欄はリソースの作成時に設定できますがその後のリクエストでは変更することはできません。

このフィールドはリクエスト上で提供されることはあるかもしれませんが、応答に入ることはありません。

旧型の認証方式。利用可能な場合は、常にAPIキーまたはOAuth 2.0の使用をお勧めします。

各APIキー：各IPアドレスにつき {maxInPeriod} 回のリクエストが {periodInSeconds} 秒ごとに送信されます

呼び出しに認証を必要としません。通常、レート制限が大幅に低下します。利用可能な場合は、常にAPIキーまたはOAuth 2.0の使用をお勧めします。

各グループ化について、スキーマ内の次のフィールドの1つのみを提供する必要があります。残りは除外できます。

いつでも再度オプトインできます。{linkStart}ご意見・ご感想をお寄せください。{linkEnd}

表示されているのは古いドキュメントです。{linkStart}ご意見・ご感想をお寄せください。{linkEnd}

いつでもオプトアウトして元のリファレンスページに戻ることができます。{linkStart}ご意見・ご感想はこちらからお寄せください。{linkEnd}

表示されているのは改訂されたドキュメントです。{linkStart}ご意見・ご感想をお寄せください。{linkEnd}

このフィールドは応答に設定できますが、リクエストでは無視されます。

注意: トラフィックが集中する時間帯には、呼び出し回数制限が低くなる場合があります。一部のエンドポイントには、追加の呼び出し回数制限が適用されます。 [呼び出し回数制限について詳しく]({link})。

ユーザー1人またはグループ1つのすべてのAPI キーで1日あたりリクエスト {limit} 回

ユーザー1人またはグループ1つのすべてのAPI キーで1時間あたりリクエスト {limit} 回

ユーザー1人またはグループ1つのすべてのAPI キーで1分あたりリクエスト {limit} 回

ユーザー1人またはグループ1つのすべてのAPI キーで1秒あたりリクエスト {limit} 回

API キー所有者1人1分あたりリクエスト {limit} 回

アプリユーザー1人1日あたりリクエスト {limit} 回

アプリユーザー1人1時間あたりリクエスト {limit} 回

アプリユーザー1人1分間あたりリクエスト {limit} 回

アプリユーザー1人1秒あたりリクエスト {limit} 回

API キー所有者1人1秒あたりリクエスト {limit} 回

スコープは、認証情報が持つ権限を制御します。認証情報は、選択したスコープでサポートされているエンドポイントにのみアクセスできます。

安定したエンドポイントは本番環境に対応しており、その存続期間中に重大な変更が発生することはほとんどありません。

このターゲットを使用すると、選択した{requiredParts}へのキーのアクセスを制限できます

このターゲットを使用すると、選択した{requiredParts}と{optionalParts}へのキーのアクセスを制限できます

ターゲットタイプは、認証情報が権限を持つリソースを制限するために使用されます。アカウントが追加のリソースに対する権限を持っている場合でも、選択されたリソースのみが実行されます。一部のスコープにはターゲットパーツがありません。この場合、関連するすべてのリソースを実行できます。

ユーザー所有のAPIキーの場合、ユニバーストップレベルパーツを選択する必要はありません。この場合、APIキーは、適切なグループ権限を持つすべてのユーザー所有のバーチャル空間とグループ所有のバーチャル空間にアクセスできます。

APIキーまたはOAuth 2.0認証を必要とするエンドポイントでは、「試してみる」はまだサポートされていません

安全のため、リスクの高い操作ではCookie認証が無効になっています。

重大なリスクのエンドポイントは非常に機密性が高く、安全のため「試してみる」は無効になっています

注：認証ヘッダーはこのコードサンプルには含まれていません。このコマンドを機能させるには、認証ヘッダーの追加が必要となる場合があります。

重要なデータを変更または削除できる高リスクのエンドポイントです。テストの際は細心の注意を払ってください。

このAPIエンドポイントは高リスクに分類されており、公開済みデータまたはユーザーアカウントに影響を与える可能性があります。

高リスクAPIへの認証済みリクエストは、元に戻せない変更を加える可能性があります。続行する前に、リクエストパラメータを注意深く確認してください。

Cookie認証を使用するにはログインしてください

データを取得する低リスクのエンドポイントです。一般的に、テストしても安全です。

データを変更する中程度のリスクのエンドポイントです。変更が永続的なものになる可能性があるため、重要でないアカウントで慎重にテストしてください。

お持ちのアカウントを保護するには、他のソースからのテキストをここに貼り付けたり、このページから他の人に情報を送信したりしないでください。

実際のアカウント認証情報を使用して、公開済みAPIエンドポイントをテストしようとしています。

行おうとしているAPI呼び出しの影響を理解している場合にのみ、続行してください。テストの前にAPIドキュメントを注意深く確認してください。

API呼び出しは、認証されたセッションを使用して行われます

アカウントまたはデータに影響を与える可能性のある実際のAPI呼び出しです

レート制限とその他のAPI制限が適用されます

一部の操作では、データが変更または削除される場合があります

このエンドポイントは、以下の推奨代替エンドポイントに置き換えられました。

このエンドポイントを呼び出すには、次のスコープが必要です。適切なキーの生成に関する詳細は、[APIキーの管理]({apiKeyReferenceDocLink})を参照してください。

キーの生成に関する詳細は、[APIキーの管理]({apiKeyReferenceDocLink})を参照してください。

次のエンドポイントは、ベースのURLに相対するパスで使用できます。

この文字列は [Timestamp](/cloud/reference/types#fieldmask) としてフォーマットされています。

JSON 値は、 `null`、 `boolean`、 `string`、 `number`、 `array`、 `object` にはできません。

あなたのOAuth 2.0 アプリケーションでこのエンドポイントを使用するには以下のスコープが必要です。OAuth 2.0 アプリケーションの登録方法についての情報は、 [アプリ登録とレビュー]({oauth2ReferenceDocLink}) をごらんください。

OAuth 2.0アプリケーションの登録方法の詳細については、[アプリの登録とレビュー]({oauth2ReferenceDocLink})を参照してください。

以下のオブジェクトは、受け入れられたか返されたペイロードの説明です。これらのオブジェクトがいつ使用されるかについて詳しくは、各エンドポイントを参照してください。

このエンドポイントを呼び出すには、次のスコープが必要です。

リソースパス

この文字列は [Timestamp](/cloud/reference/types#timestamp) としてフォーマットされています。

あなたのOAuth 2.0 アプリケーションでこのエンドポイントを使用するには以下の範囲が必要です。OAuth 2.0 アプリケーションの登録方法についての情報は、 [アプリ登録とレビュー]({oauth2ReferenceDocLink}) をごらんください。

非推奨

オープンクラウド参照の改良バージョンを表示しています。

オープンクラウド参照の新バージョンからオプトアウトしました。

広告請求アカウントを表示します。

請求アカウントの環境設定を行い、広告クレジットを購入するためのアクセス権を付与します。

広告キャンペーンとその成果を表示します。

広告キャンペーンを作成、更新、管理します。

これであなたのアセットについての情報を表示できるようになります。

これでRobloxにアセットをアップロードしたり、アップデートしたりできます。

これにより、ご利用のアカウントがアクセス可能なすべての項目（グループおよびバーチャル空間を含む）とアセットに関して、アセット権限を表示できるようになります。

これは、すべての対象（グループやバーチャル空間を含む）とアカウントがアクセスできるアセットにアセット権限を付与します。

これにより、あなたに代わって行われるアバター自動設定ジョブの状況と結果を表示できるようになります。

これにより、あなたに代わって行われるアバター自動設定ジョブを作成および管理できるようになります。

ユーザー所有のバッジを更新する能力を付与。

あなたのEコマースアイテムについての情報を表示できるようにします。

これにより、同期済みのEコマースアイテムを変更できるようになります。

あなたのEコマース事業者コネクションについての情報を閲覧できるようにします。

これでEコマース事業者コネクションを編集できるようになります。

これでクリエーターストアの製品に関する情報を表示できます。

これでクリエーターストアの製品に関する情報を変更できます。

これにより、クリエーターストアの保存に関する情報を表示できます。

これにより、クリエーターストアの保存に関する情報を変更できます。

あなたの代わりにデータストアを作成する権限を付与します。

あなたに代わってデータストアを削除する権限を付与します。

データストアの一覧を読み取る権限を付与します。

データストアのスナップショットを撮る権限を付与します。

データストアに入力内容を作成する権限を付与します。

データストアの特定の入力内容に削除用の印をつける権限を付与します。

データストアの入力内容一覧にアクセスする権限を付与します。

データストアの特定の入力内容を読み取る権限を付与します。

入力内容の値、属性、ユーザーを更新する権限を付与します。

データストアの入力内容の修正記録を削除する権限を付与します。

データストアの入力内容一覧の修正記録にアクセスする権限を付与します。

データストアの入力内容の修正記録を読み込む権限を付与します。

許可されたユーザーの開発者製品の環境設定詳細を閲覧するアクセス権を付与。

許可されたユーザーの開発者製品を編集するアクセス権を付与。

あなたのユニバースの環境についての情報を表示できるようにします。

これであなたのユニバースの環境を編集できるようにします。

許可されたユーザーのゲームパスの設定詳細を閲覧するアクセス権を付与。

許可されたユーザーのゲームパスを編集するアクセス権を付与。

アカウントのコミュニティ情報を表示する権限を付与します。

アカウントのコミュニティ情報を管理するためのアクセス権を付与します。

あなたコミュニティについての情報を表示できるようにします。

これでお持ちのアカウントのコミュニティ参加リクエストと低ランクのコミュニティメンバーの役割への更新を管理できるようになります。

インスタンスのプロパティデータを表示できます。

インスタンスのプロパティデータを変更できます（現在はスクリプトのみをサポートしています）。

これであなたの持ち物についての情報を表示できるようになります。

ユーザーアセット管理のアクセス権を付与。

あなたのバッジ管理へのアクセス権を付与。

バッジ管理とRobuxの使用管理機能へのアクセス権を付与。

承認済みユーザーのバッジを更新する権限を付与します。

あなたの開発者製品の管理機能へのアクセス権を付与。

通知をオンにしているバーチャル空間についての情報を読むアクセス権を付与します。

あなたに代わって通知をオンまたはオフにするアクセス権を付与します。

あなたのパス管理へのアクセス権を付与。

あなたのコミュニティ管理へのアクセス権を付与。

コミュニティ情報を読む権限を付与。

コミュニティ管理権限を付与。

多言語化テーブルの読み込みと書き込みへのアクセス権を付与

あなたが所有するすべてのバーチャル空間に関するチーム共同制作管理へのアクセス権を付与。

あなたのバーチャル空間の管理機能と、関連する特定の情報へのアクセス権を付与。（例：多言語化の情報）

バーチャル空間の多言語化情報を読むアクセス権を付与。

バーチャル空間の多言語化設定を変更するためのアクセス権を付与。

あなたのユーザーアカウントへのアクセス権を付与。

ユーザーの多言語化設定を変更するアクセス権を付与。

関連するプレースのLuau実行タスクのステータス、ログ、結果を表示できます。

関連するプレースに対して、新しいLuau実行タスクを作成できます。

これにより、マーケットプレイスアイテムの内容審査への異議申し立ての状況を表示できます。

これにより、マーケットプレイスアイテムの内容審査への異議申し立てを提出できます。

これにより、マーケットプレイスへの新規アイテムやバンドルの公開、リミテッドアイテムの再入荷が可能になります。公開や再入荷を行うと、アカウントからRobuxが消費される場合があります。

これにより、マーケットプレイスアイテムとバンドル（価格、手数料、フォルダ、公開設定を含む）を閲覧できます。

これにより、マーケットプレイスのアップロード手数料とRobux残高を表示できます。

これにより、マーケットプレイスアイテム（価格、セールスケジュール、表示情報、フォルダを含む）の更新と非公開化が可能になります。

ユニバース内のすべてのデータ構造を非同期的にフラッシュするためのアクセス権を付与。

新しいキューアイテムを作成するためのアクセス権を付与。

キューの先頭から読み取りアイテムを破棄するためのアクセス権を付与。

キューの先頭からアイテムを読み取るためのアクセス権を付与。

メモリストアアイテムを読み込むためのアクセス権を付与。

マップアイテムを読み込むためのアクセス権を付与。

マップアイテムの作成、更新、削除へのアクセス権を付与。

これでユーザーに代わってメッセージを公開する権限を与えることができます。

これでバーチャル空間からユーザーに通知を送信できるようになります。

（非推奨）順序付けられたデータストア内のエントリのリストを読み込むためのアクセス権を付与。

（非推奨）順序付けられたデータストアに新しいエントリーを作成するためのアクセス権を付与。

順序付けられたデータストアからのリストエントリーへのアクセス権を付与。

順序付けられたデータストアにエントリーを作成するためのアクセス権を付与。

これであなたのバーチャル空間に関連した秘密をリストアップできるようになります。

これであなたのバーチャル空間に関連した秘密を作成してアップデートできるようになります。

この権限を使用すると、評価ジョブを送信してジョブの結果を表示できます。

あなたの定期購入製品についての内容を読む権限を付与。

これにより、あなたに代わってサムネイル情報を読み取れるようになります。

解析アラートを読み取る能力を付与します。

解析アラートを作成または変更する能力を付与します。

カスタム解析ダッシュボードを読み取る権限を付与します。

カスタム解析ダッシュボードを作成または変更する権限を付与します。

ゲーム解析を読み取る能力を付与します。

ゲーム解析に関連するリソースに書き込む権限を付与します。

バーチャル空間の広告掲載基準、広告設定、および広告プレースメントを確認しましょう。

広告設定を変更し、バーチャル空間の広告プレースメントを作成または更新しましょう。

プレース情報を読み取る能力を付与。

プレース情報を編集する能力を付与。

Robloxにバーチャル空間の新しいバージョンを公開する権限を付与します。

これにより、バーチャル空間のサムネイルおよびサムネイルのパーソナライズ設定を読み取ることができます。

これにより、バーチャル空間のサムネイルのアップロードや削除、およびサムネイルのパーソナライズ設定の管理を行うことができます。

バーチャル空間の情報を読む能力を付与。

承認済みユーザーのバーチャル空間を編集する権限を付与します。

バーチャル空間内でのユーザー制限を表示できます。

バーチャル空間内でのユーザー制限が編集できるようになります。

これにより、ご利用のアカウントに送信された通知を表示できるようになります。

承認済みユーザーがプレミアム会員がどうかと認証済みかどうかを読み取る権限を付与します。

これで承認済みユーザーのSNSアカウントを閲覧できるようになります。

ゲームのイベントを読み取る能力を付与します。

ゲームのイベントを編集する能力を付与します。

シングルサインオン機能を有効化。

これにより、あなたのプロフィール情報を読む権限が与えられます。

概要