このページでは、Google ドキュメント、スプレッドシート、スライドのユーザーがサードパーティ サービスからリンクをプレビューできる Google Workspace アドオンを作成する方法について説明します。
Google Workspace アドオンは、サービスのリンクを検出し、ユーザーにプレビューを促すことができます。サポートケース、見込み顧客、従業員プロフィールへのリンクなど、複数の URL パターンをプレビューするようにアドオンを構成できます。
ユーザーがリンクをプレビューする方法
リンクをプレビューするには、スマートチップやカードを操作します。
ユーザーがドキュメントに URL を入力または貼り付けると、リンクをスマートチップに置き換えるように求めるメッセージが Google ドキュメントに表示されます。スマートチップには、アイコンと、リンクのコンテンツの短いタイトルまたは説明が表示されます。ユーザーがチップにカーソルを合わせると、ファイルやリンクに関する詳細情報をプレビューするカード インターフェースが表示されます。
次の動画は、ユーザーがリンクをスマートチップに変換し、カードをプレビューする方法を示しています。
スプレッドシートとスライドでリンクをプレビューする方法
スプレッドシートとスライドのリンク プレビューでは、サードパーティのスマートチップはサポートされていません。ユーザーがスプレッドシートやプレゼンテーションに URL を入力または貼り付けると、Google スプレッドシートまたはスライドで、リンクをチップではなくリンクテキストとしてタイトルに置き換えるよう求めるメッセージが表示されます。ユーザーがリンクのタイトルにカーソルを合わせると、リンクに関する情報をプレビューするカード インターフェースが表示されます。
次の図は、スプレッドシートとスライドでリンク プレビューがどのように表示されるかを示しています。
前提条件
Apps Script
- Google Workspace アカウント。
- Google Workspace アドオン。アドオンを構築するには、このquickstartに従ってください。
Node.js
- Google Workspace アカウント。
- Google Workspace アドオン。アドオンを構築するには、このquickstartに従ってください。
Python
- Google Workspace アカウント。
- Google Workspace アドオン。アドオンを構築するには、このquickstartに従ってください。
Java
- Google Workspace アカウント。
- Google Workspace アドオン。アドオンを構築するには、このquickstartに従ってください。
省略可: サードパーティ サービスに対する認証を設定する
承認が必要なサービスにアドオンを接続した場合、ユーザーはリンクをプレビューするためにサービスの認証を行う必要があります。つまり、ユーザーがサービスからのリンクをドキュメント、スプレッドシート、スライドのファイルに初めて貼り付けるとき、アドオンは承認フローを呼び出す必要があります。
OAuth サービスまたはカスタム認証プロンプトを設定するには、次のいずれかのガイドをご覧ください。
Apps Script を使用してアドオンを作成した場合は、Google Workspace アドオンから Google 以外のサービスに接続するをご覧ください。
別のランタイムを使用してアドオンを作成した場合は、アドオンをサードパーティ サービスに接続するをご覧ください。
アドオンのリンク プレビューを設定する
このセクションでは、アドオンのリンク プレビューを設定する方法について説明します。これには次の手順が含まれます。
- アドオンのデプロイ リソースまたはマニフェスト ファイルでリンク プレビューを構成します。
- リンクのスマートチップとカード インターフェースを作成します。
リンク プレビューを設定する
リンク プレビューを構成するには、アドオンのデプロイ リソースまたはマニフェスト ファイルで次のセクションとフィールドを指定します。
addOns
セクションに、ドキュメントを拡張するdocs
フィールド、スプレッドシートを拡張するsheets
フィールド、スライドを拡張するslides
フィールドを追加します。各フィールドで、
runFunction
を含むlinkPreviewTriggers
トリガーを実装します(この関数は、次のセクションのスマートチップとカードを作成するで定義します)。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
を引数として渡します。このイベント オブジェクトのペイロードを使用して、リンク プレビュー用のスマートチップとカードをビルドします。
たとえば、ユーザーが Google ドキュメントでリンク 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
をスペイン語にローカライズします。
Deployment リソース
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"
}
]
}
}
}