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

本页面介绍如何构建 Google Workspace 插件，以便 Google 文档用户能够预览来自第三方服务的链接。

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

用户如何预览链接

如需预览 Google 文档中的链接，用户可以与智能条状标签和卡片进行互动：

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

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

前提条件

Apps 脚本

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

Node.js

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

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

Python

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

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

Java

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

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

如果您的插件连接到需要授权的服务，则用户必须验证该服务才能预览链接。这意味着，当用户首次将您服务中的链接粘贴到 Google 文档文档中时，您的插件必须调用授权流程。

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

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

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

为插件设置链接预览

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

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

配置链接预览

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

1. 在 addOns 部分下，添加 docs 字段以扩展 Google 文档。

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

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

3. 在 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 插件会预览公司的支持请求服务链接。该插件指定了三种网址格式来预览链接。每当链接与 Google 文档文档中的某个网址格式匹配时，回调函数 caseLinkPreview 都会构建并显示智能条状标签和卡片。

构建智能条状标签和卡片

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

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

例如，对于指定网址格式 example.com/cases 的插件，如果用户预览链接 https://www.example.com/cases/123456，系统会返回以下事件载荷：

JSON

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

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

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

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

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

以下代码会创建回调函数 caseLinkPreview：

Apps 脚本

apps-script/preview-links/preview-link.gs

在 GitHub 上查看

/**
* Entry point for a support case link preview
*
* @param {!Object} event
* @return {!Card}
*/
// Creates a function that passes an event object as a parameter.
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 ID.
    const segments = event.docs.matchedUrl.url.split('/');
    const caseId = segments[segments.length - 1];

    // Builds a preview card with the case ID, title, and description
    const caseHeader = CardService.newCardHeader()
      .setTitle(`Case ${caseId}: Title bar is broken.`);
    const caseDescription = CardService.newTextParagraph()
      .setText('Customer can\'t view title on mobile device.');

    // 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();
  }
}

Node.js

node/preview-links/index.js

在 GitHub 上查看

/**
 * 
 * A support case link preview.
 *
 * @param {!string} url
 * @return {!Card}
 */
function caseLinkPreview(url) {

  // Parses the URL to identify the case ID.
  const segments = url.split('/');
  const caseId = segments[segments.length - 1];

  // Returns the card.
  // Uses the text from the card's header for the title of the smart chip.
  return {
    header: {
      title: `Case ${caseId}: Title bar is broken.`
    },
    sections: [{
      widgets: [{
        textParagraph: {
          text: `Customer can't view title on mobile device.`
        }
      }]
    }]
  };
}

Python

python/preview-links/main.py

在 GitHub 上查看

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

    # Parses the URL to identify the case ID.
    segments = url.split("/")
    case_id = segments[-1]

    # Returns the card.
    # Uses the text from the card's header for the title of the smart chip.
    return {
        "header": {"title": f"Case {case_id}: Title bar is broken."},
        "sections": [
            {
                "widgets": [
                    {
                        "textParagraph": {
                            "text": "Customer can't view title on mobile device."
                        }
                    }
                ]
            }
        ],
    }

Java

java/preview-links/src/main/java/PreviewLink.java

在 GitHub 上查看

/**
 * Creates a case link preview card.
 *
 * @param url A URL.
 * @return A case link preview card.
 */
Card caseLinkPreview(String url) {
  String[] segments = url.split("/");
  String caseId = segments[segments.length - 1];

  CardHeader cardHeader = new CardHeader();
  cardHeader.setTitle(String.format("Case %s: Title bar is broken.", caseId));

  TextParagraph textParagraph = new TextParagraph();
  textParagraph.setText("Customer can't view title on mobile device.");

  WidgetMarkup widget = new WidgetMarkup();
  widget.setTextParagraph(textParagraph);
  Section section = new Section();
  section.setWidgets(List.of(widget));

  Card card = new Card();
  card.setHeader(cardHeader);
  card.setSections(List.of(section));

  return card;
}

预览卡片支持的组件

对于链接预览卡片，Google Workspace 插件支持以下 widget 和操作：

Apps 脚本

“银行卡服务”字段	类型
TextParagraph	widget
DecoratedText	widget
Image	widget
IconImage	widget
ButtonSet	widget
TextButton	widget
ImageButton	widget
Grid	widget
Divider	widget
OpenLink	操作
Navigation	操作 仅支持 updateCard 方法。

JSON

卡片 (google.apps.card.v1) 字段	类型
TextParagraph	widget
DecoratedText	widget
Image	widget
Icon	widget
ButtonList	widget
Button	widget
Grid	widget
Divider	widget
OpenLink	操作
Navigation	操作 。仅支持 updateCard 方法。

完整示例：支持请求插件

以下示例展示了 Google Workspace 插件，该插件可以预览指向公司支持请求和员工个人资料的链接。

该示例执行以下操作：

• 预览链接，指向支持案例，例如 https://www.example.com/support/cases/1234。智能条状标签会显示支持图标，预览卡片包含支持请求 ID 和说明。
• 预览支持请求代理（例如 https://www.example.com/people/rosario-cruz）的链接。智能条状标签显示一个人形图标，预览卡片上包含员工的姓名、电子邮件地址、职位和个人资料照片。
• 如果用户的语言区域设置为西班牙语，则智能条状标签会将其 labelText 本地化为西班牙语。

Deployment 资源

Apps 脚本

apps-script/preview-links/appsscript.json

在 GitHub 上查看

{
  "timeZone": "America/New_York",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "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": "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"
        },
        {
          "runFunction": "peopleLinkPreview",
          "patterns": [
            {
              "hostPattern": "example.com",
              "pathPrefix": "people"
            }
          ],
          "labelText": "People",
          "localizedLabelText": {
            "es": "Personas"
          },
          "logoUrl": "https://developers.google.com/workspace/add-ons/images/person-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/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"
        }
      ]
    }
  }
}

编码

Apps 脚本

apps-script/preview-links/preview-link.gs

在 GitHub 上查看

/**
* Entry point for a support case link preview
*
* @param {!Object} event
* @return {!Card}
*/
// Creates a function that passes an event object as a parameter.
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 ID.
    const segments = event.docs.matchedUrl.url.split('/');
    const caseId = segments[segments.length - 1];

    // Builds a preview card with the case ID, title, and description
    const caseHeader = CardService.newCardHeader()
      .setTitle(`Case ${caseId}: Title bar is broken.`);
    const caseDescription = CardService.newTextParagraph()
      .setText('Customer can\'t view title on mobile device.');

    // 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();
  }
}


/**
* Entry point for an employee profile link preview
*
* @param {!Object} event
* @return {!Card}
*/
function peopleLinkPreview(event) {

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

    // Builds a preview card with an employee's name, title, email, and profile photo.
    const userHeader = CardService.newCardHeader().setTitle("Rosario Cruz");
    const userImage = CardService.newImage()
      .setImageUrl("https://developers.google.com/workspace/add-ons/images/employee-profile.png");
    const userInfo = CardService.newDecoratedText()
      .setText("[e-mail]")
      .setBottomLabel("Case Manager")
      .setIcon(CardService.Icon.EMAIL);
    const userSection = CardService.newCardSection()
      .addWidget(userImage)
      .addWidget(userInfo);

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

Node.js

node/preview-links/index.js

在 GitHub 上查看

const UrlParser = require('url');

/**
 * Responds to any HTTP request.
 *
 * @param {Object} req HTTP request context.
 * @param {Object} res HTTP response context.
 */
exports.createLinkPreview = (req, res) => {
  const event = req.body;
  if (event.docs.matchedUrl.url) {
    res.json(createCard(event.docs.matchedUrl.url));
  }
};

/**
 * Creates a preview link card for either a case link or people link.
 * 
 * @param {!String} url
 * @return {!Card}
 */
function createCard(url) {
  const parsedUrl = UrlParser.parse(url);
  if (parsedUrl.hostname === 'www.example.com') {
    if (parsedUrl.path.startsWith('/support/cases/')) {
      return caseLinkPreview(url);
    }

    if (parsedUrl.path.startsWith('/people/')) {
      return peopleLinkPreview();
    }
  }
}


/**
 * 
 * A support case link preview.
 *
 * @param {!string} url
 * @return {!Card}
 */
function caseLinkPreview(url) {

  // Parses the URL to identify the case ID.
  const segments = url.split('/');
  const caseId = segments[segments.length - 1];

  // Returns the card.
  // Uses the text from the card's header for the title of the smart chip.
  return {
    header: {
      title: `Case ${caseId}: Title bar is broken.`
    },
    sections: [{
      widgets: [{
        textParagraph: {
          text: `Customer can't view title on mobile device.`
        }
      }]
    }]
  };
}


/**
 * An employee profile link preview.
 *
 * @return {!Card}
 */
function peopleLinkPreview() {

  // Builds a preview card with an employee's name, title, email, and profile photo.
  // Returns the card. Uses the text from the card's header for the title of the smart chip.
  return {
    header: {
      title: "Rosario Cruz"
    },
    sections: [{
      widgets: [
        {
          image: {
            imageUrl: 'https://developers.google.com/workspace/add-ons/images/employee-profile.png'
          }
        }, {
          keyValue: {
            icon: "EMAIL",
            content: "[e-mail]",
            bottomLabel: "Case Manager"
          }
        }
      ]
    }]
  };
}

Python

python/preview-links/main.py

在 GitHub 上查看

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

import flask
import functions_framework


@functions_framework.http
def create_link_preview(req: flask.Request):
    """Responds to any HTTP request.
    Args:
      req: HTTP request context.
    Returns:
      The response object.
    """
    event = req.get_json(silent=True)
    if event["docs"]["matchedUrl"]["url"]:
        return create_card(event["docs"]["matchedUrl"]["url"])


def create_card(url):
    """Creates a preview link card for either a case link or people link.
    Args:
      url: The matched url.
    Returns:
      A case link preview card or a people link preview card.
    """
    parsed_url = urlparse(url)
    if parsed_url.hostname != "www.example.com":
        return {}

    if parsed_url.path.startswith("/support/cases/"):
        return case_link_preview(url)

    if parsed_url.path.startswith("/people/"):
        return people_link_preview()

    return {}




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

    # Parses the URL to identify the case ID.
    segments = url.split("/")
    case_id = segments[-1]

    # Returns the card.
    # Uses the text from the card's header for the title of the smart chip.
    return {
        "header": {"title": f"Case {case_id}: Title bar is broken."},
        "sections": [
            {
                "widgets": [
                    {
                        "textParagraph": {
                            "text": "Customer can't view title on mobile device."
                        }
                    }
                ]
            }
        ],
    }




def people_link_preview():
    """An employee profile link preview.
    Returns:
      A people link preview card.
    """

    # Builds a preview card with an employee's name, title, email, and profile photo.
    # Returns the card. Uses the text from the card's header for the title of the smart chip.
    return {
        "header": {"title": "Rosario Cruz"},
        "sections": [
            {
                "widgets": [
                    {
                        "image": {
                            "imageUrl": "https:#developers.google.com/workspace/add-ons/images/employee-profile.png"
                        }
                    },
                    {
                        "keyValue": {
                            "icon": "EMAIL",
                            "content": "[e-mail]",
                            "bottomLabel": "Case Manager",
                        }
                    },
                ]
            }
        ],
    }

Java

java/preview-links/src/main/java/PreviewLink.java

在 GitHub 上查看

import com.google.api.services.chat.v1.model.Card;
import com.google.api.services.chat.v1.model.CardHeader;
import com.google.api.services.chat.v1.model.Image;
import com.google.api.services.chat.v1.model.KeyValue;
import com.google.api.services.chat.v1.model.Section;
import com.google.api.services.chat.v1.model.TextParagraph;
import com.google.api.services.chat.v1.model.WidgetMarkup;
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.JsonObject;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.List;

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

  /**
   * Responds to any HTTP request.
   *
   * @param request  An HTTP request context.
   * @param response An HTTP response context.
   */
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    JsonObject body = gson.fromJson(request.getReader(), JsonObject.class);
    String url = body.getAsJsonObject("docs")
        .getAsJsonObject("matchedUrl")
        .get("url")
        .getAsString();

    response.getWriter().write(gson.toJson(createCard(url)));
  }

  /**
   * Creates a preview link card for either a case link or people link.
   *
   * @param url A URL.
   * @return A case link preview card or a people link preview card.
   */
  Card createCard(String url) throws MalformedURLException {
    URL parsedURL = new URL(url);

    if (!parsedURL.getHost().equals("www.example.com")) {
      return new Card();
    }

    if (parsedURL.getPath().startsWith("/support/cases/")) {
      return caseLinkPreview(url);
    }

    if (parsedURL.getPath().startsWith("/people/")) {
      return peopleLinkPreview();
    }

    return new Card();
  }


  /**
   * Creates a case link preview card.
   *
   * @param url A URL.
   * @return A case link preview card.
   */
  Card caseLinkPreview(String url) {
    String[] segments = url.split("/");
    String caseId = segments[segments.length - 1];

    CardHeader cardHeader = new CardHeader();
    cardHeader.setTitle(String.format("Case %s: Title bar is broken.", caseId));

    TextParagraph textParagraph = new TextParagraph();
    textParagraph.setText("Customer can't view title on mobile device.");

    WidgetMarkup widget = new WidgetMarkup();
    widget.setTextParagraph(textParagraph);
    Section section = new Section();
    section.setWidgets(List.of(widget));

    Card card = new Card();
    card.setHeader(cardHeader);
    card.setSections(List.of(section));

    return card;
  }


  /**
   * Creates a people link preview card.
   *
   * @return A people link preview card.
   */
  Card peopleLinkPreview() {
    CardHeader cardHeader = new CardHeader();
    cardHeader.setTitle("Rosario Cruz");

    Image image = new Image();
    image.setImageUrl("https://developers.google.com/workspace/add-ons/images/employee-profile.png");

    WidgetMarkup imageWidget = new WidgetMarkup();
    imageWidget.setImage(image);

    KeyValue keyValue = new KeyValue();
    keyValue.setIcon("EMAIL");
    keyValue.setContent("[e-mail]");
    keyValue.setBottomLabel("Case Manager");

    WidgetMarkup keyValueWidget = new WidgetMarkup();
    keyValueWidget.setKeyValue(keyValue);

    Section section = new Section();
    section.setWidgets(List.of(imageWidget, keyValueWidget));

    Card card = new Card();
    card.setHeader(cardHeader);
    card.setSections(List.of(section));

    return card;
  }

}

相关资源

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