firestore-data

使用方法

すべてのスクリプトは Node.js で実行できます。<param_name> と <param_value> は実際の値に置き換えてください。

Bash: node <skill_dir>/scripts/<script_name>.js '{"<param_name>": "<param_value>"}'

PowerShell: node <skill_dir>/scripts/<script_name>.js '{\"<param_name>\": \"<param_value>\"}'

注：スクリプトは、さまざまな .env ファイルから環境変数を自動的に読み込みます。環境変数が不足してスキルの実行に失敗した場合を除き、ユーザーに変数の設定を求めないでください。

スクリプト

add_documents

Firestore コレクションに新しいドキュメントを追加します。次のベストプラクティスに従ってください：

1. documentData では常に型付きの値を使用してください。各フィールドは適切な型インジケーターで囲む必要があります（例：{"stringValue": "text"}）。
2. documentData の整数値は文字列で指定できます。このツールは整数値を文字列として受け付けます（例：{"integerValue": "1500"}）。
3. returnData は必要な場合にのみ true に設定してください。書き込まれた正確なデータの確認が必要な場合にのみ設定します。
4. 送信前にデータを検証してください。データが Firestore のネイティブ JSON 形式に準拠していることを確認してください。
5. タイムスタンプは適切に処理してください。タイムスタンプ文字列には RFC3339 形式を使用してください。
6. バイナリデータは Base64 でエンコードしてください。バイナリデータは bytesValue フィールドで Base64 エンコードする必要があります。
7. セキュリティルールを考慮してください。対象コレクションでのドキュメント作成が Firestore のセキュリティルールで許可されていることを確認してください。

パラメーター

名前	型	説明	必須	デフォルト
collectionPath	文字列	ドキュメントを追加するコレクションの相対パスです（例：'users' または 'users/userId/posts'）。注：これは相対パスであり、'projects/{project_id}/databases/{database_id}/documents/...' のような絶対パスではありません。	はい
documentData	オブジェクト	Firestore のネイティブ JSON 形式のドキュメントデータです。各フィールドは型インジケーターで囲む必要があります：

• 文字列：{"stringValue": "text"}
• 整数：{"integerValue": "123"} または {"integerValue": 123}
• 浮動小数点数：{"doubleValue": 123.45}
• ブール値：{"booleanValue": true}
• タイムスタンプ：{"timestampValue": "2025-01-07T10:00:00Z"}
• 地理座標：{"geoPointValue": {"latitude": 34.05, "longitude": -118.24}}
• 配列：{"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}}
• マップ：{"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}}
• Null：{"nullValue": null}
• バイト列：{"bytesValue": "base64EncodedString"}
• 参照：{"referenceValue": "collection/document"} | はい | | | returnData | ブール値 | true に設定すると、出力に作成されたドキュメントのデータが含まれます。このフラグを false に設定すると、エージェントのコンテキストが過剰になるのを防げます。 | いいえ | false |

---

delete_documents

Firestore から複数のドキュメントを削除します

パラメーター

名前	型	説明	必須	デフォルト
documentPaths	配列	Firestore から削除するドキュメントの相対パスの配列です（例：'users/userId' または 'users/userId/posts/postId'）。注：これらは相対パスであり、'projects/{project_id}/databases/{database_id}/documents/...' のような絶対パスではありません。	はい

---

get_documents

パスを指定して、Firestore から複数のドキュメントを取得します

パラメーター

名前	型	説明	必須	デフォルト
documentPaths	配列	Firestore から取得するドキュメントの相対パスの配列です（例：'users/userId' または 'users/userId/posts/postId'）。注：これらは相対パスであり、'projects/{project_id}/databases/{database_id}/documents/...' のような絶対パスではありません。	はい

---

list_collections

指定した親パスの Firestore コレクションを一覧表示します

パラメーター

名前	型	説明	必須	デフォルト
parentPath	string	サブコレクションの一覧を取得する相対親ドキュメントパス（例：'users/userId'）。指定しない場合は、ルートコレクションの一覧を取得します。注：これは相対パスであり、'projects/{project_id}/databases/{database_id}/documents/...'のような絶対パスではありません	いいえ

---

query_collection

現在のプロジェクトのデータベース内にあるコレクションから、完全なドキュメントパスで指定したコレクションの Firestore ドキュメントを1件以上取得します。 コレクションの正確なパスと、ドキュメントに適用したいフィルタ条件がわかっている場合に使用してください。

パラメーター

名前	型	説明	必須	デフォルト
collectionPath	string	クエリ対象の Firestore コレクションへの相対パス（例：'users' または 'users/userId/posts'）。注：これは相対パスであり、'projects/{project_id}/databases/{database_id}/documents/...'のような絶対パスではありません	はい
filters	array	クエリに適用するフィルターオブジェクトの配列です。各フィルターは、次の内容を含む JSON 文字列です： - field：フィルター対象のフィールド名 - op：使用する演算子（"<", "<=", ">", ">=", "==", "!=", "array-contains", "array-contains-any", "in", "not-in"） - value：比較対象の値（文字列、数値、ブール値、または配列） 例：{"field": "age", "op": ">", "value": 18}	はい
orderBy	string	並べ替え対象のフィールドと方向を指定する JSON 文字列（例：{"field": "name", "direction": "ASCENDING"}）。指定しない場合は空欄にします	はい
limit	integer	返すドキュメントの最大数	いいえ	100
analyzeQuery	boolean	true の場合、実行統計を含むクエリの説明メトリクスを返します	いいえ	false

---

update_document

Firestore の既存ドキュメントを更新します。ドキュメント全体の更新と、更新マスクを使用した特定フィールドの更新の両方に対応しています。次のベストプラクティスに従ってください：

1. 正確に更新するには更新マスクを使用します。特定のフィールドのみを更新する場合は、意図しない変更を防ぐためにupdateMaskパラメーターを使用します
2. documentDataでは必ず型付きの値を使用します。各フィールドは適切な型インジケーターでラップする必要があります（例：{"stringValue": "text"}）
3. 更新マスクを使ってフィールドを削除します。削除するフィールドをupdateMaskに含め、documentDataからは省略します
4. 整数値は文字列で指定できます。このスキルでは整数値を文字列として受け付けます（例：{"integerValue": "1500"}）
5. returnDataは必要な場合にのみtrueに設定し、更新後の正確なデータを確認するときに限って使用します
6. タイムスタンプは適切に処理します。タイムスタンプ文字列にはRFC3339形式を使用します
7. セキュリティルールを考慮します。Firestoreのセキュリティルールでドキュメントの更新が許可されていることを確認してください

パラメーター

名前	型	説明	必須	デフォルト
documentPath	string	更新するドキュメントの相対パスです（例：'users/userId' または 'users/userId/posts/postId'）。注：これは相対パスであり、'projects/{project_id}/databases/{database_id}/documents/...' のような絶対パスではありません。	はい
documentData	object	Firestore ネイティブの JSON 形式のドキュメントデータです。各フィールドは型を示す値で囲む必要があります： - 文字列：{"stringValue": "text"} - 整数：{"integerValue": "123"} または {"integerValue": 123} - 浮動小数点数：{"doubleValue": 123.45} - ブール値：{"booleanValue": true} - タイムスタンプ：{"timestampValue": "2025-01-07T10:00:00Z"} - 地理座標：{"geoPointValue": {"latitude": 34.05, "longitude": -118.24}} - 配列：{"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}} - マップ：{"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}} - Null：{"nullValue": null} - バイト列：{"bytesValue": "base64EncodedString"} - 参照：{"referenceValue": "collection/document"}	はい
updateMask	array	更新対象のフィールドを指定します。指定しない場合、documentData 内のすべてのフィールドが更新されます。指定した場合、指定されたフィールドのみが更新されます。マスクで参照されているものの documentData に存在しないフィールドは、ドキュメントから削除されます。	いいえ
returnData	boolean	true に設定すると、更新後のドキュメントのデータが出力されます。このフラグを false に設定すると、エージェントのコンテキストが過剰になるのを防げます。	いいえ	false

---