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

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

Google Workspace 插件可以检测您服务的链接，并提示用户预览这些链接。您可以将插件配置为预览多个网址模式，例如支持请求、销售线索和员工个人资料的链接。

用户如何预览链接

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

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

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

用户如何在幻灯片中预览链接

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

下图展示了链接预览在幻灯片中的呈现方式：

前提条件

Apps 脚本

• 一个 Google Workspace 账号。
• Google Workspace 插件。如需构建 插件，请按照此 快速入门进行操作。

Node.js

• 一个 Google Workspace 账号。
• Google Workspace 插件。如需构建 插件，请按照此 快速入门进行操作。

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

Python

• 一个 Google Workspace 账号。
• Google Workspace 插件。如需构建 插件，请按照此 快速入门进行操作。

注意 ：本指南中的 Python 代码示例旨在作为 Cloud Functions 函数运行，并 使用 Python 3.9。

Java

• 一个 Google Workspace 账号。
• Google Workspace 插件。如需构建 插件，请按照此 快速入门进行操作。

可选：设置对第三方服务的身份验证

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

如需设置 OAuth 服务或自定义授权提示，请参阅将插件连接到第三方服务。

为插件设置链接预览

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

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

配置链接预览

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

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

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

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

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

例如，请参阅以下清单的 oauthScopes 和 addons 部分，该清单为支持请求服务配置了链接预览。

注意： 对于幻灯片， labelText 和 localizedLabelText 不会呈现，但您必须添加 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"
    }
  }
}

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

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

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

注意： 对于链接预览，系统会为每位用户缓存卡片响应 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 插件支持以下微件和操作，用于链接预览卡片：

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 本地化为西班牙语。

清单

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 文档清单
• 链接预览的卡片界面