使用智能条状标签预览链接（开发者预览版）

。

本页介绍了如何构建可让 Google 文档用户预览第三方服务链接的 Google Workspace 插件。

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 互动功能的回调函数。例如，如果您添加了内容为“查看链接”的按钮，则可以创建一个用于指定回调函数的操作，用于在新窗口中打开链接。如需详细了解 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 插件支持以下微件和操作：

Apps 脚本

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

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 文档部署资源
• 用于链接预览的卡片界面