本頁面由 Cloud Translation API 翻譯而成。

透過智慧型方塊預覽連結

本頁面說明如何建構 Google Workspace 外掛程式，讓 Google 文件、試算表和簡報使用者預覽第三方服務的連結。

Google Workspace 外掛程式可偵測服務的連結，並提示使用者預覽。您可以設定外掛程式來預覽多個網址模式，例如客服案件連結、銷售待開發客戶和員工個人資料的連結。

使用者預覽連結的方式

如要預覽連結，使用者可以與智慧型方塊和資訊卡互動。

使用者預覽資訊卡

當使用者在文件中輸入或貼上網址時，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 外掛程式預覽了公司的客服案件服務連結。這個外掛程式會指定三種預覽連結的網址模式。只要連結符合其中一個網址模式，回呼函式 caseLinkPreview 就會建構並顯示資訊卡和智慧型方塊 (或在試算表和簡報中)，將網址替換成連結標題。

打造智慧型方塊和卡片

如要傳回連結的智慧型方塊和資訊卡，您必須實作在 linkPreviewTriggers 物件中指定的任何函式。

當使用者與符合指定網址模式的連結互動時，linkPreviewTriggers 觸發條件會啟動，其回呼函式會將事件物件 EDITOR_NAME.matchedUrl.url 做為引數傳遞。您可以使用這個事件物件的酬載，為連結預覽建構智慧型方塊和資訊卡。

舉例來說，如果使用者在 Google 文件中預覽 https://www.example.com/cases/123456 連結，系統就會傳回下列事件酬載：

JSON

{
  "docs": {
    "matchedUrl": {
        "url": "https://www.example.com/support/cases/123456"
    }
  }
}

如要建立資訊卡介面，請使用小工具顯示連結的相關資訊。您也可以建立動作，讓使用者開啟連結或修改內容。如需可用的小工具和動作清單，請參閱「預覽資訊卡支援的元件」。

如何為連結預覽建立智慧型方塊和資訊卡：

實作您在外掛程式部署資源或資訊清單檔案的 linkPreviewTriggers 部分指定的函式：
1. 此函式必須接受包含 EDITOR_NAME.matchedUrl.url 的事件物件做為引數，並傳回單一 Card 物件。
2. 如果您的服務需要授權，該函式也必須叫用授權流程。
請在每張預覽資訊卡中實作可為介面提供小工具互動功能的回呼函式。舉例來說，如果您加入「查看連結」按鈕，可以建立一個動作來指定回呼函式，以在新視窗中開啟連結。如要進一步瞭解小工具互動，請參閱「外掛程式動作」。

下列程式碼會建立文件的回呼函式 caseLinkPreview：

Apps Script

apps-script/3p-resources/3p-resources.gs

前往 GitHub 查看

/**
* Entry point for a support case link preview.
*
* @param {!Object} event The event object.
* @return {!Card} The resulting preview link card.
*/
function caseLinkPreview(event) {

  // If the event object URL matches a specified pattern for support case links.
  if (event.docs.matchedUrl.url) {

    // Uses the event object to parse the URL and identify the case details.
    const caseDetails = parseQuery(event.docs.matchedUrl.url);

    // Builds a preview card with the case name, and description
    const caseHeader = CardService.newCardHeader()
      .setTitle(`Case ${caseDetails["name"][0]}`);
    const caseDescription = CardService.newTextParagraph()
      .setText(caseDetails["description"][0]);

    // Returns the card.
    // Uses the text from the card's header for the title of the smart chip.
    return CardService.newCardBuilder()
      .setHeader(caseHeader)
      .addSection(CardService.newCardSection().addWidget(caseDescription))
      .build();
  }
}

/**
* Extracts the URL parameters from the given URL.
*
* @param {!string} url The URL to parse.
* @return {!Map} A map with the extracted URL parameters.
*/
function parseQuery(url) {
  const query = url.split("?")[1];
  if (query) {
    return query.split("&")
    .reduce(function(o, e) {
      var temp = e.split("=");
      var key = temp[0].trim();
      var value = temp[1].trim();
      value = isNaN(value) ? value : Number(value);
      if (o[key]) {
        o[key].push(value);
      } else {
        o[key] = [value];
      }
      return o;
    }, {});
  }
  return null;
}

Node.js

node/3p-resources/index.js

前往 GitHub 查看

/**
 * 
 * A support case link preview.
 *
 * @param {!URL} url The event object.
 * @return {!Card} The resulting preview link card.
 */
function caseLinkPreview(url) {
  // Builds a preview card with the case name, and description
  // Uses the text from the card's header for the title of the smart chip.
  // Parses the URL and identify the case details.
  const name = `Case ${url.searchParams.get("name")}`;
  return {
    action: {
      linkPreview: {
        title: name,
        previewCard: {
          header: {
            title: name
          },
          sections: [{
            widgets: [{
              textParagraph: {
                text: url.searchParams.get("description")
              }
            }]
          }]
        }
      }
    }
  };
}

Python

python/3p-resources/create_link_preview/main.py

前往 GitHub 查看


def case_link_preview(url):
    """A support case link preview.
    Args:
      url: A matching URL.
    Returns:
      The resulting preview link card.
    """

    # Parses the URL and identify the case details.
    query_string = parse_qs(url.query)
    name = f'Case {query_string["name"][0]}'
    # Uses the text from the card's header for the title of the smart chip.
    return {
        "action": {
            "linkPreview": {
                "title": name,
                "previewCard": {
                    "header": {
                        "title": name
                    },
                    "sections": [{
                        "widgets": [{
                            "textParagraph": {
                                "text": query_string["description"][0]
                            }
                        }]
                    }],
                }
            }
        }
    }

Java

java/3p-resources/src/main/java/CreateLinkPreview.java

前往 GitHub 查看

/**
 * A support case link preview.
 *
 * @param url A matching URL.
 * @return The resulting preview link card.
 */
JsonObject caseLinkPreview(URL url) throws UnsupportedEncodingException {
  // Parses the URL and identify the case details.
  Map<String, String> caseDetails = new HashMap<String, String>();
  for (String pair : url.getQuery().split("&")) {
      caseDetails.put(URLDecoder.decode(pair.split("=")[0], "UTF-8"), URLDecoder.decode(pair.split("=")[1], "UTF-8"));
  }

  // Builds a preview card with the case name, and description
  // Uses the text from the card's header for the title of the smart chip.
  JsonObject cardHeader = new JsonObject();
  String caseName = String.format("Case %s", caseDetails.get("name"));
  cardHeader.add("title", new JsonPrimitive(caseName));

  JsonObject textParagraph = new JsonObject();
  textParagraph.add("text", new JsonPrimitive(caseDetails.get("description")));

  JsonObject widget = new JsonObject();
  widget.add("textParagraph", textParagraph);

  JsonArray widgets = new JsonArray();
  widgets.add(widget);

  JsonObject section = new JsonObject();
  section.add("widgets", widgets);

  JsonArray sections = new JsonArray();
  sections.add(section);

  JsonObject previewCard = new JsonObject();
  previewCard.add("header", cardHeader);
  previewCard.add("sections", sections);

  JsonObject linkPreview = new JsonObject();
  linkPreview.add("title", new JsonPrimitive(caseName));
  linkPreview.add("previewCard", previewCard);

  JsonObject action = new JsonObject();
  action.add("linkPreview", linkPreview);

  JsonObject renderActions = new JsonObject();
  renderActions.add("action", action);

  return renderActions;
}

預覽資訊卡支援的元件

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 Workspace 外掛程式，供您預覽公司在 Google 文件中客服案件的連結。

本範例會執行下列作業：

預覽客服案件連結，例如 https://www.example.com/support/cases/1234。智慧型方塊會顯示支援圖示，預覽資訊卡則包含案件 ID 和說明。
如果使用者的語言代碼設為西班牙文，智慧型方塊就會將其 labelText 本地化為西班牙文。

部署資源

Apps Script

Apps-script/3p-resources/appsscript.json

前往 GitHub 查看

{
  "timeZone": "America/New_York",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/workspace.linkpreview",
    "https://www.googleapis.com/auth/workspace.linkcreate"
  ],
  "addOns": {
    "common": {
      "name": "Manage support cases",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.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",
          "localizedLabelText": {
            "es": "Caso de soporte"
          },
          "logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
        }
      ],
      "createActionTriggers": [
        {
          "id": "createCase",
          "labelText": "Create support case",
          "localizedLabelText": {
            "es": "Crear caso de soporte"
          },
          "runFunction": "createCaseInputCard",
          "logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
        }
      ]
    }
  }
}

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"
        }
      ]
    }
  }
}

程式碼

Apps Script

apps-script/3p-resources/3p-resources.gs

前往 GitHub 查看

/**
* Entry point for a support case link preview.
*
* @param {!Object} event The event object.
* @return {!Card} The resulting preview link card.
*/
function caseLinkPreview(event) {

  // If the event object URL matches a specified pattern for support case links.
  if (event.docs.matchedUrl.url) {

    // Uses the event object to parse the URL and identify the case details.
    const caseDetails = parseQuery(event.docs.matchedUrl.url);

    // Builds a preview card with the case name, and description
    const caseHeader = CardService.newCardHeader()
      .setTitle(`Case ${caseDetails["name"][0]}`);
    const caseDescription = CardService.newTextParagraph()
      .setText(caseDetails["description"][0]);

    // Returns the card.
    // Uses the text from the card's header for the title of the smart chip.
    return CardService.newCardBuilder()
      .setHeader(caseHeader)
      .addSection(CardService.newCardSection().addWidget(caseDescription))
      .build();
  }
}

/**
* Extracts the URL parameters from the given URL.
*
* @param {!string} url The URL to parse.
* @return {!Map} A map with the extracted URL parameters.
*/
function parseQuery(url) {
  const query = url.split("?")[1];
  if (query) {
    return query.split("&")
    .reduce(function(o, e) {
      var temp = e.split("=");
      var key = temp[0].trim();
      var value = temp[1].trim();
      value = isNaN(value) ? value : Number(value);
      if (o[key]) {
        o[key].push(value);
      } else {
        o[key] = [value];
      }
      return o;
    }, {});
  }
  return null;
}

Node.js

node/3p-resources/index.js

前往 GitHub 查看

/**
 * Responds to any HTTP request related to link previews.
 *
 * @param {Object} req An HTTP request context.
 * @param {Object} res An HTTP response context.
 */
exports.createLinkPreview = (req, res) => {
  const event = req.body;
  if (event.docs.matchedUrl.url) {
    const url = event.docs.matchedUrl.url;
    const parsedUrl = new URL(url);
    // If the event object URL matches a specified pattern for preview links.
    if (parsedUrl.hostname === 'example.com') {
      if (parsedUrl.pathname.startsWith('/support/cases/')) {
        return res.json(caseLinkPreview(parsedUrl));
      }
    }
  }
};


/**
 * 
 * A support case link preview.
 *
 * @param {!URL} url The event object.
 * @return {!Card} The resulting preview link card.
 */
function caseLinkPreview(url) {
  // Builds a preview card with the case name, and description
  // Uses the text from the card's header for the title of the smart chip.
  // Parses the URL and identify the case details.
  const name = `Case ${url.searchParams.get("name")}`;
  return {
    action: {
      linkPreview: {
        title: name,
        previewCard: {
          header: {
            title: name
          },
          sections: [{
            widgets: [{
              textParagraph: {
                text: url.searchParams.get("description")
              }
            }]
          }]
        }
      }
    }
  };
}

Python

python/3p-resources/create_link_preview/main.py

前往 GitHub 查看

from typing import Any, Mapping
from urllib.parse import urlparse, parse_qs

import flask
import functions_framework


@functions_framework.http
def create_link_preview(req: flask.Request):
    """Responds to any HTTP request related to link previews.
    Args:
      req: An HTTP request context.
    Returns:
      An HTTP response context.
    """
    event = req.get_json(silent=True)
    if event["docs"]["matchedUrl"]["url"]:
        url = event["docs"]["matchedUrl"]["url"]
        parsed_url = urlparse(url)
        # If the event object URL matches a specified pattern for preview links.
        if parsed_url.hostname == "example.com":
            if parsed_url.path.startswith("/support/cases/"):
                return case_link_preview(parsed_url)

    return {}




def case_link_preview(url):
    """A support case link preview.
    Args:
      url: A matching URL.
    Returns:
      The resulting preview link card.
    """

    # Parses the URL and identify the case details.
    query_string = parse_qs(url.query)
    name = f'Case {query_string["name"][0]}'
    # Uses the text from the card's header for the title of the smart chip.
    return {
        "action": {
            "linkPreview": {
                "title": name,
                "previewCard": {
                    "header": {
                        "title": name
                    },
                    "sections": [{
                        "widgets": [{
                            "textParagraph": {
                                "text": query_string["description"][0]
                            }
                        }]
                    }],
                }
            }
        }
    }

Java

java/3p-resources/src/main/java/CreateLinkPreview.java

前往 GitHub 查看

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import com.google.gson.Gson;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;
import com.google.gson.JsonPrimitive;

import java.io.UnsupportedEncodingException;
import java.net.URL;
import java.net.URLDecoder;
import java.util.HashMap;
import java.util.Map;

public class CreateLinkPreview implements HttpFunction {
  private static final Gson gson = new Gson();

  /**
   * Responds to any HTTP request related to link previews.
   *
   * @param request An HTTP request context.
   * @param response An HTTP response context.
   */
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
    String url = event.getAsJsonObject("docs")
        .getAsJsonObject("matchedUrl")
        .get("url")
        .getAsString();
    URL parsedURL = new URL(url);
    // If the event object URL matches a specified pattern for preview links.
    if ("example.com".equals(parsedURL.getHost())) {
      if (parsedURL.getPath().startsWith("/support/cases/")) {
        response.getWriter().write(gson.toJson(caseLinkPreview(parsedURL)));
        return;
      }
    }

    response.getWriter().write("{}");
  }


  /**
   * A support case link preview.
   *
   * @param url A matching URL.
   * @return The resulting preview link card.
   */
  JsonObject caseLinkPreview(URL url) throws UnsupportedEncodingException {
    // Parses the URL and identify the case details.
    Map<String, String> caseDetails = new HashMap<String, String>();
    for (String pair : url.getQuery().split("&")) {
        caseDetails.put(URLDecoder.decode(pair.split("=")[0], "UTF-8"), URLDecoder.decode(pair.split("=")[1], "UTF-8"));
    }

    // Builds a preview card with the case name, and description
    // Uses the text from the card's header for the title of the smart chip.
    JsonObject cardHeader = new JsonObject();
    String caseName = String.format("Case %s", caseDetails.get("name"));
    cardHeader.add("title", new JsonPrimitive(caseName));

    JsonObject textParagraph = new JsonObject();
    textParagraph.add("text", new JsonPrimitive(caseDetails.get("description")));

    JsonObject widget = new JsonObject();
    widget.add("textParagraph", textParagraph);

    JsonArray widgets = new JsonArray();
    widgets.add(widget);

    JsonObject section = new JsonObject();
    section.add("widgets", widgets);

    JsonArray sections = new JsonArray();
    sections.add(section);

    JsonObject previewCard = new JsonObject();
    previewCard.add("header", cardHeader);
    previewCard.add("sections", sections);

    JsonObject linkPreview = new JsonObject();
    linkPreview.add("title", new JsonPrimitive(caseName));
    linkPreview.add("previewCard", previewCard);

    JsonObject action = new JsonObject();
    action.add("linkPreview", linkPreview);

    JsonObject renderActions = new JsonObject();
    renderActions.add("action", action);

    return renderActions;
  }

}

透過智慧型方塊預覽連結

使用者預覽連結的方式

使用者如何在試算表和簡報中預覽連結

必備條件

Apps Script

Node.js

Python

Java

選用：設定第三方服務的驗證機制

設定外掛程式的連結預覽

設定連結預覽

打造智慧型方塊和卡片

JSON

Apps Script

Node.js

Python

Java

預覽資訊卡支援的元件

Apps Script

JSON

完整範例：客服案件外掛程式

部署資源

Apps Script

JSON

程式碼

Apps Script

Node.js

Python

Java

相關資源