kintone レコードを読み書きする非公式のプラグイン

Author: r3-yamauchi
Version: 0.2.0
Type: tool

Description

これは kintone アプリのレコードを読み書きしたり、添付ファイルをアップロード/ダウンロードする際に便利な機能を提供する、非公式の Dify 用ツール・プラグインです。ソースコードを GitHub リポジトリで公開しています。

⚠️ 注意: このプラグインは非公式です
このプラグインは kintone の提供元であるサイボウズが開発・保守しているものではありません。コミュニティによって開発された非公式のプラグインです。ご利用は自己責任でお願いいたします。サイボウズ公式のプラグインは https://marketplace.dify.ai/plugins/cybozu/kintone で公開されています。

Features

kintoneのドメインとアプリIDを指定してレコードを取得
kintoneのドメインとアプリIDを指定してフィールド定義を取得
kintoneのクエリ構文仕様文字列を取得
kintone レコード配列 JSON をフラット化
kintoneのドメインとアプリIDを指定してレコードを1件新規追加
レコードIDまたはupdateKeyを指定してレコードを1件更新
構文のリファレンスを取得
の内容を検証
kintoneレコードのコメント欄へ（メンション付きで）投稿
レコードIDを指定してコメントを取得
複数レコードを一括追加・更新（upsert）
JSON文字列または配列からupdateKey付きのupsert用を生成
JSON文字列または配列からkintoneテーブル(SUBTABLE)行構造を生成
fileKeyを指定してkintoneからファイルをダウンロード
ファイルをkintoneへアップロードし、一時的なfileKeyを取得

Prerequisites

対象のkintoneアプリを閲覧する権限を持つAPIトークン

APIトークン以外の認証方式に対応していません。 Basic認証や SAML認証にも対応していません。

設定

プラグインのプロバイダー設定画面でとの値を入力できます。APIトークンはカンマ区切り形式（例: ）で最大9個まで指定でき、10個以上を指定するとエラーになります。
各ツールでも APIトークンを指定できます。各ツールで指定しない場合はプロバイダー設定値が使われ、指定するとその値が上書き使用されます（プロバイダー設定したAPIトークンは使用されません）

Usage Examples

1. kintone Query

1. 指定したkintoneアプリのすべてのレコードを取得する

2. の値が100以上のレコードのみ取得する

3. 指定したフィールドの値のみを取得する

任意パラメータ: （秒）を指定するとAPIタイムアウトを調整できます（既定値30秒）。

パラメータを指定すると、出力形式を選べます。

値	挙動
(既定)	テキストと JSON をまとめて返却
	テキストのみ
	JSON をページ単位で逐次返却（テキストは省略）
	kintoneレコードをフラットなオブジェクト配列に変換して返却

レスポンス例は次の通りです。

2. kintone Get Fields

1. 対象アプリのフィールド定義を取得する（ただし基本的な情報のみ）

フィールドコードやフィールドタイプといった基本的な情報を返します。
関連レコードの情報は返しません。

2. フル情報を取得する

をにすると、kintone が返すフィールド定義を全てそのまま返します。
省略またはの場合は主要情報のみです。

3. kintone Query Docs

1. バンドルされているクエリ構文ドキュメントを取得する

kintoneのクエリ構文に関する説明文書を返します。

4. kintone Flatten JSON

が返したレコード配列 JSON を扱いやすいフラットなオブジェクトに変換します。

1. レコード配列全体をフラット化する

レスポンス（JSON とテキスト出力は同じ内容）:

2. 特定のテーブル行だけを抽出し、フィールドを絞り込む

レスポンス:

を指定すると、そのテーブルの行のみが返り、（カンマ区切り）を指定すると指定したフィールドが出力に追加されます。

5. kintone Add Record

1. レコードを 1件新規追加する

任意パラメータ: （秒）でAPIタイムアウトを変更できます。既定値は10秒です。

6. kintone Update Record

既存レコードを1件更新します。対象レコードが存在しない場合はエラーになります。
Upsert（レコードがなければ追加）する必要がある場合はを使用してください。

の形式はと同じで、指定したフィールドのみ更新されます。

を指定する場合

を形式で指定する場合

にフィールドコードのみ、値はで分けて指定する場合

またはのいずれかを指定してください。は上記 2) または 3) の形式を選べます。

7. kintone Record Data Docs

やで利用するのJSON構文ガイドを返します。引数は不要で、サンプル構造、フィールドタイプ別ルール、バリデーション仕様、よくあるエラーを含む文章を返します。

8. kintone Validate Record Data

やに渡すための JSON 文字列を、アプリのフィールド定義に基づいて問題がないかを検証します。

構造および型チェックを通過すると、整形済みの JSON をそのまま返します。例えば内で指定されたフィールドが対象アプリに存在しないなどの理由で検証に失敗した場合は、具体的なエラー内容をメッセージとして返します。

9. kintone Add Record Comment

1. レコードコメントを投稿する

には最大 10,000 文字までのテキストを指定できます。は任意で、のような JSON 配列を渡すと、コメントにメンションを追加できます。には / / を指定でき、最大10件までメンション可能です。

成功時には以下の情報が得られます。

変数 : kintoneが返したJSON（作成者やタイムスタンプを含む）
出力: , , , , をまとめたサマリー
出力: 投稿結果のメッセージ

任意パラメータ: （秒）でコメント投稿APIのタイムアウトを変更できます（既定値10秒）。

10. kintone Get Record Comments

レコードIDを指定して、当該レコードに投稿されているコメントを取得します。
パラメータを指定せずを既定値の 0 と指定した場合は、当該レコードの全てのコメントを取得します。

1. コメントIDの昇順で全件取得

2. 最新のものから順に（降順に） 15 件のみ取得

11. kintone Upsert Records

1. 複数のレコードを一度に追加する

2. updateKeyを使用して既存のレコードを更新する

12. kintone Build Records Data

JSON文字列または配列のオブジェクトから、が期待するを生成し、指定したを自動で付与します。

レスポンス例:

13. kintone Build Subtable Rows

JSON文字列または配列を、kintoneテーブル(SUBTABLE)フィールドが受け付ける形式に変換します。

レスポンス例:

配列をそのまま渡すことも可能です。

14. kintone Download File

1. ファイルキーを指定してkintoneからファイルをダウンロードする

ファイルキーの取得方法

ファイルキーを取得するには：

ツールを使用して添付ファイルフィールドを含むレコードを取得
レスポンス内の添付ファイルフィールド値を確認（例：）
の値を、このツールのパラメータとして使用

15. kintone Upload File

1. 添付ファイルをアップロードして fileKey を取得する

には 1件以上のファイルを指定できます。任意でを指定できます。

応答では変数が常に返り、の入ったオブジェクトのリストとして利用できます。

単一ファイル例:
複数ファイル例:

ファイルをアップロードすると kintone内の一時保管領域にファイルが保存され、一時保管領域用のが発行されます。このを使用して kintoneレコードの添付ファイルフィールドにファイルを添付できます。レコードに添付しない場合、一時保管領域のファイルは 3日間で削除されます。

標準出力の扱いは次のとおりです。

: を指定しない場合は、指定した場合はが格納されるため、そのままに渡せます。
: 上記 JSON と同じ内容を文字列として出力します。
互換性確保のため / の変数メッセージも従来どおり返します。

主なパラメータ:

（必須, files）: アップロードするファイル本体を1件以上指定します。
（任意, 文字列またはJSON配列）: kintoneへ渡すファイル名を上書きします。単一ファイル時は文字列、複数ファイル時はファイル数と同数の配列（例: ）。
（任意, 文字列またはJSONオブジェクト）: 向けのペイロードを自動生成する設定を渡します（詳細は下記参照）。
（任意, 数値）: kintone API 呼び出しのタイムアウト秒数（既定値 30 秒）。

records_mapping を指定すると、という JSON 文字列も出力され、そのままのに渡せます。

任意パラメータを指定すると、kintone へ送信するファイル名を上書きできます。単一ファイル時は文字列、複数ファイル時はファイル数と同じ要素数の JSON 配列（例: ）を指定してください。

は配列を含む JSON です。各要素には必須の（添付フィールド名）と、任意の / を含められます。ファイルの割り当てルールは以下のとおりです。

が1件のみ: アップロードした全てのファイルをその1件に添付。
の件数 = アップロードしたファイル数: アップロード順に 1件ずつ対応付け。

具体例:

すべてのファイルを1件にまとめて添付（updateKey あり）

ファイルを1つずつ別レコードへ割り当て（ファイル2件 → records も2件）

レコードごとに追加フィールドを入れつつ1対1で割り当て

ルールまとめ: は空であってはならず、各要素にが必須です。は省略可能ですがオブジェクトである必要があります。を複数指定する場合、配列の長さはアップロードしたファイル数と一致させてください（1件ずつ割り当て）。

アップサート動作: を指定すると、該当レコードがあれば更新、なければ新規追加（Upsert）になります。を指定しない場合は常に新規レコードとして追加されます。

を使用しない場合は、Dify の標準ノードを積み上げてを構築します。例えば以下のような構成です。

for-each（イテレーション）ノード — をループし、やを利用してと対応するを取得します（既存レコードを特定する値は、入力フォームや前段の検索ノードから受け取ります）。
テンプレート（JSON）ノード — ループ結果を使ってを生成し、添付フィールドにを差し込みます。必要に応じてを使い、複数の fileKey を 1レコードにまとめる配列を事前に作成します。
kintone_upsert_records ノード — テンプレート出力をとして渡し、アップロードしたファイルを添付します。

この構成なら、を使わずともファイルごとの割り当て方法（1レコードにまとめる／レコードごとに分配する等）を柔軟に制御できます。Collection ノードを併用すれば、ループで収集した fileKey の配列を 1レコードに集約することも容易です。

また、Python スクリプトノードでを組み立てる方法もあります。出力から fileKey を取得し、下記のようなスクリプトで JSON 文字列を生成すれば、同じくにそのまま渡せます。

を指定すればこれらのノード（あるいはスクリプト）を省略でき、 → を直接つなぐだけで済むため、ワークフローの簡潔さが格段に向上します。

あわせて、アップロード結果を説明するテキストメッセージが返ります。単一ファイルの場合は例: 、複数ファイルの場合はのように件数とファイル名／fileKey の一覧が通知されます。

任意パラメータ: （秒）で一括リクエストのタイムアウトを設定できます（既定値30秒）。

** 「kintone」はサイボウズ株式会社の登録商標です。

ここに記載している内容は情報提供を目的としており、個別のサポートはできません。
設定内容についてのご質問やご自身の環境で動作しないといったお問い合わせをいただいても対応はできませんので、ご了承ください。
**

kintone レコードを読み書きする 非公式 のプラグイン