スマートチップ

このガイドでは、Google スプレッドシート API を使用してスプレッドシートにスマートチップを追加、管理する方法とその理由について説明します。

スマートチップとは

スマートチップを使用すると、他の Google Workspace アプリケーションからリッチでインタラクティブなデータをスプレッドシートに直接取り込むことができます。スマートチップを使用すると、ユーザーは情報とアクションにすばやくアクセスでき、セルリンクを動的オブジェクトに変換できます。詳しくは、Google スプレッドシートにスマートチップを挿入するをご覧ください。

スマートチップを追加する

チップはチップ行として表され、CellData の一部であるため、UpdateCellsRequest または AppendCellsRequest を指定して既存の spreadsheets.batchUpdate メソッドを使用してチップを挿入できます。

リクエストに chipRuns フィールドを含める必要があります。チップ実行は、チップのプロパティと、セルのテキスト内の位置を記述します。

chipRuns を作成する際は、追加するチップごとにプレースホルダ文字（@）を含む userEnteredValue も指定する必要があります。chipRuns 配列内の各実行は、いずれかのプレースホルダに対応します。チップなしの実行は、書き込み時に省略できます。

次の例は、ファイルチップ、ユーザーチップ、プレーンテキストを 1 つのセル（A1）に書き込む方法を示しています。* {JSON}

        {
          "updateCells": {
            "rows": [
              {
                "values": [
                  {
                    "userEnteredValue": {
                      "stringValue": "@ is the owner of @."
                    },
                    "chipRuns": [
                      {
                        "chip": {
                          "personProperties": {
                            "email": "johndoe@gmail.com",
                            "displayFormat": "DEFAULT"
                          }
                        }
                      },
                      {
                        "startIndex": 18,
                        "chip": {
                          "richLinkProperties": {
                            "uri": "https://docs.google.com/document/d/YOUR_DOCUMENT_ID/edit"
                          }
                        }
                      }
                    ]
                  }
                ]
              }
            ],
            "fields": "userEnteredValue,chipRuns",
            "range": {
              "startRowIndex": 0,
              "startColumnIndex": 0
            }
          }
        }

チップのプロパティを構成する

チップ オブジェクトには、次のいずれかのプロパティ タイプを指定できます。

personProperties

連絡先チップを作成する場合に使用します。

  • email:（必須）リンクするユーザーのメールアドレス。
  • displayFormat: （省略可）人物の名前の優先表示形式。次のいずれか 1 つを指定できます。
    • DEFAULT: 標準の「姓名」形式。
    • LAST_NAME_COMMA_FIRST_NAME: 「姓、名」形式。
    • EMAIL: ユーザーのメールアドレス。

これを使用して、リッチリンク チップを作成します。API はさまざまな Google サービス（YouTube やカレンダーなど）へのリンクを読み取れますが、チップとして書き込めるのは Google ドライブ ファイルへのリンクのみです。

  • uri:（必須）リソースの URI。作成の場合は、Google ドライブ ファイルのリンクにする必要があります。URI は 2,000 バイトを超えないようにしてください。

スマートチップを読み取る

スマートチップのデータを読み取るには、spreadsheets.get メソッドを使用し、fields パラメータに sheets.data.rowData.values(chipRuns) を含めます。

レスポンスの chipRuns 配列には、セルのテキストのすべてのサブセクションのオブジェクトが含まれます。

  • チップ付きの走行: これらのセクションには、personProperties または richLinkProperties を含む chip オブジェクトが入力されます。
  • チップなしの実行: プレーンテキスト セクションにも実行オブジェクトがありますが、その chip フィールドは空になります。

チップの表示テキストを取得するには、formattedValue をフィールドとして追加します。

スマートチップを更新する

スマートチップを更新または置き換えるには、セルのコンテンツを上書きする必要があります。チップを追加する場合と同じ UpdateCellsRequest または AppendCellsRequest を使用し、新しい userEnteredValue と chipRun を指定します。セル内の既存のチップが置き換えられます。

スプレッドシートの他の機能でスマートチップを使用する

表: スマートチップをテーブルの列タイプとして使用して、プロジェクト オーナー（ユーザー チップ）や関連ドキュメント（ファイル チップ）を追跡できます。

フィルタ: 範囲内のスマートチップのテキスト値に基づいて範囲をフィルタできます。