このページでは、Google ドキュメント、スプレッドシート、スライドのユーザーがサードパーティ サービスのリンクをプレビューできる Google Workspace アドオンを作成する方法について説明します。
Google Workspace アドオンは、サービスのリンクを検出して、ユーザーにプレビューするよう促すことができます。アドオンを構成して、サポートケース、営業見込み客、従業員プロファイルへのリンクなど、複数の URL パターンをプレビューできます。
ユーザーがリンクをプレビューする方法
ユーザーは、リンクをプレビューするために、 スマートチップと カードを操作します。
ユーザーがドキュメントまたはスプレッドシートに URL を入力するか貼り付けると、Google ドキュメントまたは Google スプレッドシート でリンクをスマートチップに置換するよう求めるメッセージが表示されます。スマートチップには、リンクされたコンテンツのアイコンと短いタイトルまたは説明が表示されます。ユーザーがチップにカーソルを合わせると、ファイルまたはリンクの詳細情報をプレビューするカード インターフェースが表示されます。
次の動画では、ユーザーがリンクをスマートチップに変換してカードをプレビューする方法を示します。
ユーザーがスライドでリンクをプレビューする方法
スライドのリンク プレビューでは、サードパーティのスマートチップはサポートされていません。ユーザーがプレゼンテーションに URL を入力するか貼り付けると、スライドでリンクをチップではなくリンクされたテキストとしてタイトルに置き換えるよう求めるメッセージが表示されます。ユーザーがリンクのタイトルにカーソルを合わせると、リンクに関する情報をプレビューするカード インターフェースが表示されます。
次の画像は、スライドでのリンク プレビューのレンダリング方法を示しています。

前提条件
Apps Script
- Google Workspace アカウント。
- Google Workspace アドオン。アドオンを作成するには、こちらの クイックスタートに沿って操作してください。
Node.js
- Google Workspace アカウント。
- Google Workspace アドオン。アドオンを作成するには、こちらの クイックスタートに沿って操作してください。
Python
- Google Workspace アカウント。
- Google Workspace アドオン。アドオンを作成するには、こちらの クイックスタートに沿って操作してください。
Java
- Google Workspace アカウント。
- Google Workspace アドオン。アドオンを作成するには、こちらの クイックスタートに沿って操作してください。
省略可: サードパーティ サービスへの認証を設定する
アドオンが認可を必要とするサービスに接続する場合、ユーザーはリンクをプレビューするためにサービスに対して認証を行う必要があります。つまり、ユーザーがサービスからドキュメント、スプレッドシート、スライドのファイルにリンクを初めて貼り付けるときに、アドオンが認可フローを呼び出す必要があります。
OAuth サービスまたはカスタム認可プロンプトを設定するには、アドオンをサードパーティ サービスに接続するをご覧ください。
アドオンのリンク プレビューを設定する
このセクションでは、アドオンのリンク プレビューを設定する方法について説明します。手順は次のとおりです。
- リンク プレビューを構成するには、アドオンのマニフェストで 設定します。
- リンクのスマートチップとカード インターフェースを作成します。
リンク プレビューを構成する
リンク プレビューを構成するには、アドオンのマニフェストで次のセクションとフィールドを指定します。
addOnsセクションで、ドキュメントを拡張するdocsフィールド、スプレッドシートを拡張するsheetsフィールド、スライドを拡張するslidesフィールドを追加します。各フィールドで、
linkPreviewTriggersトリガー を実装します。これには、runFunction(この関数は、次の セクションのスマートチップとカードを作成するで定義します)が含まれます。linkPreviewTriggersトリガーで指定できるフィールドについては、Apps Script マニフェストまたは 他の ランタイムのデプロイ リソースのリファレンス ドキュメントをご覧ください。oauthScopesフィールドにスコープhttps://www.googleapis.com/auth/workspace.linkpreviewを追加して、ユーザーがアドオンに代わってリンクをプレビューする権限を付与できるようにします。
例として、サポートケース サービスのリンク プレビューを構成する次のマニフェストの oauthScopes セクションと addons セクションをご覧ください。
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://www.example.com/images/company-logo.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
},
"sheets": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
},
"slides": {
"linkPreviewTriggers": [
{
"runFunction": "caseLinkPreview",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"logoUrl": "https://www.example.com/images/support-icon.png",
"localizedLabelText": {
"es": "Caso de soporte"
}
}
]
}
}
}
この例では、Google Workspace アドオンは、企業のサポートケース サービスのリンクをプレビューします。アドオンは、リンクをプレビューする 3 つの URL パターンを指定します。リンクが URL パターンのいずれかに一致すると、コールバック関数 caseLinkPreview はドキュメント、スプレッドシート、スライドでカードとスマートチップを作成して表示し、URL をリンクのタイトルに置き換えます。
スマートチップとカードを作成する
リンクのスマートチップとカードを返すには、linkPreviewTriggers オブジェクトで指定した関数を実装する必要があります。
ユーザーが指定された URL パターンに一致するリンクを操作すると、
linkPreviewTriggers トリガーが起動し、そのコールバック関数がイベント
オブジェクト EDITOR_NAME.matchedUrl.url を引数として渡します。このイベント オブジェクトのペイロードを使用して、リンク プレビューのスマートチップとカードを作成します。
たとえば、ユーザーがドキュメントでリンク https://www.example.com/cases/123456 をプレビューすると、次のイベント ペイロードが返されます。
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
カード インターフェースを作成するには、ウィジェットを使用してリンクに関する情報を表示します。ユーザーがリンクを開いたり、その内容を変更したりできるアクションを作成することもできます。使用可能なウィジェットとアクションの一覧については、プレビュー カードでサポートされている コンポーネントをご覧ください。
リンク プレビューのスマートチップとカードを作成するには:
- アドオンのマニフェストの
linkPreviewTriggersセクションで指定した関数を実装します。- 関数は、
EDITOR_NAME.matchedUrl.urlを含むイベント オブジェクトを引数として受け取り、 単一のCardオブジェクトを返す必要があります。 - サービスで認可が必要な場合は、関数で 認可フローも呼び出す必要があります。
- 関数は、
- プレビュー カードごとに、インターフェースのウィジェットのインタラクティビティを提供するコールバック関数を実装します。たとえば、「リンクを表示」というボタンを追加する場合は、新しいウィンドウでリンクを開くコールバック関数を指定するアクションを作成できます。ウィジェットの操作について詳しくは、アドオンのアクションをご覧ください。
次のコードでは、ドキュメントのコールバック関数 caseLinkPreview を作成します。
Apps Script
Node.js
Python
Java
プレビュー カードでサポートされているコンポーネント
Google Workspace アドオンは、リンク プレビュー カードで次のウィジェットとアクションをサポートしています。
Apps Script
| カード サービスのフィールド | タイプ |
|---|---|
TextParagraph |
ウィジェット |
DecoratedText |
ウィジェット |
Image |
ウィジェット |
IconImage |
ウィジェット |
ButtonSet |
ウィジェット |
TextButton |
ウィジェット |
ImageButton |
ウィジェット |
Grid |
ウィジェット |
Divider |
ウィジェット |
OpenLink |
アクション |
Navigation |
アクション updateCard メソッドのみがサポートされています。 |
JSON
カード(google.apps.card.v1)フィールド |
タイプ |
|---|---|
TextParagraph |
ウィジェット |
DecoratedText |
ウィジェット |
Image |
ウィジェット |
Icon |
ウィジェット |
ButtonList |
ウィジェット |
Button |
ウィジェット |
Grid |
ウィジェット |
Divider |
ウィジェット |
OpenLink |
アクション |
Navigation |
アクション updateCard メソッドのみがサポートされています。 |
完全な例: サポートケース アドオン
次の例では、Google ドキュメントで企業のサポートケースへのリンクをプレビューする Google Workspace アドオンを紹介します。
この例では、次のことを行います。
https://www.example.com/support/cases/1234などのサポートケースへのリンクをプレビューします。スマートチップにはサポート アイコンが表示され、プレビュー カードにはケース ID と説明が表示されます。- ユーザーのロケールがスペイン語に設定されている場合、スマートチップは
labelTextをスペイン語にローカライズします。
マニフェスト
Apps Script
JSON
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"localizedLabelText": {
"es": "Caso de soporte"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
}
]
}
}
}