スマートチップ

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

スマートチップとは何ですか？

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

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

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

リクエストには 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 を指定します。これにより、セル内の既存のチップが置き換えられます。

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

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

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