使用智能条状标签预览链接

本页介绍了如何构建 Google Workspace 插件，让 Google 文档、表格和幻灯片用户能够预览来自第三方服务的链接。

Google Workspace 插件可以检测服务的链接并提示用户预览这些链接。您可以配置插件以预览多种网址格式，例如支持请求、潜在客户和员工个人资料的链接。

用户如何预览链接

如需预览链接，用户可以与智能条状标签和卡片互动。

当用户在文档中输入或粘贴网址时，Google 文档会提示他们将链接替换为智能条状标签。智能条状标签会显示一个图标以及链接内容的简短标题或说明。当用户将光标悬停在条状标签上时，他们会看到一个卡片界面，用于预览有关文件或链接的更多信息。

以下视频展示了用户如何将链接转换为智能条状标签并预览卡片：

用户如何在 Google 表格和幻灯片中预览链接

表格和幻灯片中的链接预览不支持第三方智能条状标签。当用户在电子表格或演示文稿中输入网址或将网址粘贴到电子表格或演示文稿时，Google 表格或幻灯片会提示他们将链接替换为链接文本（而不是条状标签）。当用户将鼠标悬停在链接标题上时，会看到一个卡片界面，用于预览该链接的相关信息。

下图显示了链接预览在 Google 表格和 Google 幻灯片中的呈现效果：

前提条件

Apps 脚本

• Google Workspace 帐号。
• Google Workspace 插件。如需构建插件，请按照此quickstart操作。

Node.js

• Google Workspace 帐号。
• Google Workspace 插件。如需构建插件，请按照此quickstart操作。

注意 ：本指南中的 Node.js 代码示例可作为 Cloud Functions 函数运行

Python

• Google Workspace 帐号。
• Google Workspace 插件。如需构建插件，请按照此quickstart操作。

注意 ：本指南中的 Python 代码示例使用 Python 3.9 作为 Cloud Functions 运行。

Java

• Google Workspace 帐号。
• Google Workspace 插件。如需构建插件，请按照此quickstart操作。

可选：设置向第三方服务进行身份验证

如果您的插件连接到需要授权的服务，则用户必须向该服务进行身份验证才能预览链接。这意味着，当用户首次将您服务中的链接粘贴到文档、表格或幻灯片文件中时，您的插件必须调用授权流程。

如需设置 OAuth 服务或自定义授权提示，请参阅以下指南之一：

• 如果您使用 Apps 脚本构建插件，请参阅从 Google Workspace 插件连接到非 Google 服务。

• 如果您使用其他运行时构建插件，请参阅将插件连接到第三方服务。

为您的插件设置链接预览

本部分介绍了如何为您的插件设置链接预览，其中包括以下步骤：

1. 在插件的部署资源或清单文件中配置链接预览。
2. 为您的链接构建智能条状标签和卡片界面。

配置链接预览

如需配置链接预览，请在插件的部署资源或清单文件中指定以下部分和字段：

1. 在 addOns 部分下，添加 docs 字段以扩展 Google 文档，添加 sheets 字段以扩展 Google 表格，添加 slides 字段以扩展幻灯片。

2. 在每个字段中，实现包含 runFunction 的 linkPreviewTriggers 触发器（您可以在下一部分构建智能条状标签和卡片中定义此函数）。

   如需了解您可以在 linkPreviewTriggers 触发器中指定的字段，请参阅 Apps 脚本清单文件的参考文档或其他运行时的部署资源。

3. 在 oauthScopes 字段中，添加范围 https://www.googleapis.com/auth/workspace.linkpreview，以便用户可以授权该插件代表自己预览链接。

例如，以下部署资源的 oauthScopes 和 addons 部分用于为支持请求服务配置链接预览。

注意 ：对于 Google 表格和 Google 幻灯片，labelText 和 localizedLabelText 不会渲染，但当 Google 表格和 Google 幻灯片开始支持第三方智能条状标签时，您必须添加 labelText。localizedLabelText 是可选的。

{
  "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 就会构建并显示卡片和一个智能条状标签，或者在 Google 表格和幻灯片中，将网址替换为链接标题。

构建智能芯片和卡

如需针对链接返回智能条状标签和卡片，您必须实现在 linkPreviewTriggers 对象中指定的所有函数。

当用户与符合指定网址格式的链接互动时，会触发 linkPreviewTriggers 触发器，并且其回调函数会将事件对象 EDITOR_NAME.matchedUrl.url 作为参数传递。您将使用此事件对象的载荷为链接预览构建智能条状标签和卡片。

例如，如果用户在 Google 文档中预览 https://www.example.com/cases/123456 链接，系统会返回以下事件载荷：

JSON

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

为了创建卡片界面，您可以使用 widget 来显示链接的相关信息。您还可以构建操作，允许用户打开链接或修改其内容。如需查看可用的 widget 和操作的列表，请参阅预览卡片支持的组件。

如需构建用于链接预览的智能条状标签和卡片，请执行以下操作：

1. 实现您在插件的部署资源或清单文件的 linkPreviewTriggers 部分中指定的函数：
   1. 该函数必须接受包含 EDITOR_NAME.matchedUrl.url 的事件对象作为参数，并返回单个 Card 对象。
   2. 如果您的服务需要授权，该函数还必须调用授权流程。
2. 对于每张预览卡片，请实现任何为接口提供 widget 交互性的回调函数。例如，如果您添加一个显示“查看链接”的按钮，则可以创建一个操作，指定用于在新窗口中打开链接的回调函数。如需详细了解 widget 交互，请参阅附加操作。

注意 ：对于链接预览，卡片响应会为每位用户缓存 5 分钟。在此期间，如果用户预览链接，则会收到缓存的响应。系统会在用户刷新文件时或在 5 分钟后清除缓存。如果返回的卡片的标题已更改，应用会提示用户刷新标题。

以下代码会为 Google 文档创建回调函数 caseLinkPreview：

Apps 脚本

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 插件支持以下 widget 和操作：

Apps 脚本

“银行卡服务”字段	类型
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 本地化为西班牙语。

Deployment 资源

Apps 脚本

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

注意 ：如需使用以下部署资源，请将 URL 值替换为已部署函数的网址。您可以使用代码示例部署该函数。

{
  "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 脚本

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;
  }

}

相关资源

• 使用智能条状标签预览 Google 图书中的链接
• 测试插件
• Google 文档部署资源
• 用于链接预览的卡片界面