このページでは、Google ドキュメントのユーザーがサードパーティ サービスからリンクをプレビューできるようにする Google Workspace アドオンを作成する方法について説明します。
Google Workspace アドオンは、サービスのリンクを検出し、Google ドキュメントのユーザーにプレビューするよう求めることができます。サポートケース、見込み顧客、従業員プロフィールへのリンクなど、複数の URL パターンをプレビューするようにアドオンを構成できます。
ユーザーがリンクをプレビューする方法
Google ドキュメント ドキュメントでリンクをプレビューするには、スマートチップやカードを操作します。
ユーザーがドキュメントに URL を入力または貼り付けると、リンクをスマートチップに置き換えるように求めるプロンプトが表示されます。スマートチップには、アイコンと、リンク コンテンツの短いタイトルまたは説明が表示されます。ユーザーがチップにカーソルを合わせると、ファイルやリンクに関する詳細情報をプレビューするカード インターフェースが表示されます。
次の動画では、ユーザーがリンクをスマートチップに変換してカードをプレビューする方法を示します。
Prerequisites
Apps Script
- Google Workspace アカウント
- Google Workspace アドオン。アドオンを作成するには、このクイックスタートに沿って操作してください。
Node.js
- Google Workspace アカウント
- Google Workspace アドオン。アドオンを作成するには、このクイックスタートに沿って操作してください。
Python
- Google Workspace アカウント
- Google Workspace アドオン。アドオンを作成するには、このクイックスタートに沿って操作してください。
Java
- Google Workspace アカウント
- Google Workspace アドオン。アドオンを作成するには、このクイックスタートに沿って操作してください。
省略可: サードパーティ サービスへの認証を設定する
承認を必要とするサービスにアドオンが接続される場合、リンクをプレビューするには、ユーザーがサービスに対して認証を行う必要があります。つまり、ユーザーがサービスから Google ドキュメントのドキュメントに初めてリンクを貼り付けるときに、アドオンで認証フローを呼び出す必要があります。
OAuth サービスまたはカスタム承認プロンプトを設定するには、次のいずれかのガイドをご覧ください。
Apps Script を使用してアドオンを作成した場合は、Google Workspace アドオンから Google 以外のサービスに接続するをご覧ください。
別のランタイムを使用してアドオンを作成した場合は、アドオンをサードパーティ サービスに接続するをご覧ください。
アドオンのリンク プレビューを設定する
このセクションでは、アドオンのリンク プレビューを設定する方法について説明します。これには、次の手順が含まれます。
- アドオンのデプロイ リソースまたはマニフェスト ファイルでリンク プレビューを構成する。
- リンクのスマートチップとカード インターフェースを作成します。
リンク プレビューを設定する
リンク プレビューを構成するには、アドオンのデプロイ リソースまたはマニフェスト ファイルで次のセクションとフィールドを指定します。
addOns
セクションにdocs
フィールドを追加して、Google ドキュメントを拡張します。docs
フィールドで、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"
}
}
]
}
}
}
この例では、Google Workspace アドオンによって会社のサポートケース サービスのリンクがプレビューされます。このアドオンは、リンクをプレビューするために 3 つの URL パターンを指定します。リンクが Google ドキュメント ドキュメント内の URL パターンのいずれかと一致するたびに、コールバック関数 caseLinkPreview
がスマートチップとカードを作成して表示します。
スマートチップとカードをビルドする
リンクのスマートチップとカードを返すには、linkPreviewTriggers
オブジェクトで指定した関数を実装する必要があります。
指定された URL パターンに一致するリンクをユーザーが操作すると、linkPreviewTriggers
トリガーが呼び出され、そのコールバック関数がイベント オブジェクト docs.matchedUrl.url
を引数として渡します。このイベント オブジェクトのペイロードを使用して、リンク プレビュー用のスマートチップとカードを作成します。
たとえば、URL パターン example.com/cases
を指定するアドオンの場合、ユーザーがリンク https://www.example.com/cases/123456
をプレビューすると、次のイベント ペイロードが返されます。
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
カード インターフェースを作成するには、ウィジェットを使用してリンクに関する情報を表示します。ユーザーがリンクを開いたり、コンテンツを変更したりできるアクションを作成することもできます。利用可能なウィジェットとアクションのリストについては、プレビュー カードでサポートされているコンポーネントをご覧ください。
リンク プレビュー用のスマートチップとカードを作成するには:
- アドオンのデプロイ リソースまたはマニフェスト ファイルの
linkPreviewTriggers
セクションで指定した関数を実装します。- この関数は、
docs.matchedUrl.url
を含むイベント オブジェクトを引数として受け取り、単一のCard
オブジェクトを返す必要があります。 - サービスで認可が必要な場合は、関数が認可フローを呼び出す必要もあります。
- この関数は、
- プレビュー カードごとに、インターフェースのウィジェット インタラクティビティを提供するコールバック関数を実装します。たとえば、「リンクを表示」というボタンを含める場合、新しいウィンドウでリンクを開くコールバック関数を指定するアクションを作成できます。ウィジェットの操作の詳細については、アドオン アクションをご覧ください。
次のコードは、コールバック関数 caseLinkPreview
を作成します。
Apps Script
Node.js
Python
Java
プレビュー カードでサポートされているコンポーネント
Google Workspace アドオンは、リンク プレビュー カードで次のウィジェットとアクションをサポートしています。
Apps Script
Card Service フィールド | タイプ |
---|---|
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 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"
}
]
}
}
}