このページでは、Google ドキュメント、スプレッドシート、スライドのユーザーがサードパーティ サービスからリンクをプレビューできるようにする Google Workspace アドオンの作成方法について説明します。
Google Workspace アドオンを使用すると、サービスのリンクを検出し、ユーザーにプレビューを求めるプロンプトを表示できます。サポートケース、セールスリード、従業員プロフィールへのリンクなど、複数の URL パターンをプレビューするようにアドオンを構成できます。
ユーザーがリンクをプレビューする方法
ユーザーは、スマートチップやカードを操作して、リンクをプレビューします。
ユーザーがドキュメントに URL を入力または貼り付けると、リンクをスマートチップに置き換えるように求めるプロンプトが表示されます。スマートチップには、アイコンと、リンクのコンテンツの短いタイトルまたは説明が表示されます。ユーザーがチップにカーソルを合わせると、ファイルやリンクに関する詳細情報をプレビューするカード インターフェースが表示されます。
次の動画では、ユーザーがリンクをスマートチップに変換してカードをプレビューする方法を示しています。
スプレッドシートとスライドでのリンクのプレビュー機能
スプレッドシートとスライドのリンク プレビューのデベロッパー プレビューでは、サードパーティのスマートチップはサポートされていません。ユーザーが 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
フィールドを追加して Google ドキュメントを拡張し、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
を引数として渡します。このイベント オブジェクトのペイロードを使用して、リンク プレビュー用のスマートチップとカードを作成します。
たとえば、ドキュメントの URL パターン example.com/cases
を指定するアドオンの場合、ユーザーがリンク 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 と説明が表示されます。 - サポートケース エージェント(
https://www.example.com/people/rosario-cruz
など)へのリンクをプレビューします。スマートチップには人のアイコンが表示され、プレビュー カードには従業員の名前、メールアドレス、役職、プロフィール写真が表示されます。 - ユーザーのロケールがスペイン語に設定されている場合、スマートチップは
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/link-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"
},
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "people"
}
],
"labelText": "People",
"localizedLabelText": {
"es": "Personas"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
}
]
}
}
}