@ 메뉴에서 타사 리소스 만들기

이 페이지에서는 Google Docs 사용자가 Google Docs 내에서 서드 파티 서비스에 지원 케이스 또는 프로젝트 작업과 같은 리소스를 만들 수 있는 Google Workspace 부가기능을 빌드하는 방법을 설명합니다.

Google Workspace 부가기능을 사용하면 Docs의 @ 메뉴에 서비스를 추가할 수 있습니다. 이 부가기능은 사용자가 Docs의 양식 대화상자를 통해 서비스에서 리소스를 만들 수 있는 메뉴 항목을 추가합니다.

사용자가 리소스를 만드는 방법

Google Docs 문서 내에서 서비스에 리소스를 만들려면 사용자가 문서에 @를 입력하고 @ 메뉴에서 서비스를 선택합니다.

사용자가 카드를 미리 봅니다.

사용자가 문서에 @를 입력하고 서비스를 선택하면 리소스를 만들기 위해 필요한 양식 입력란이 포함된 카드가 표시됩니다. 사용자가 리소스 생성 양식을 제출하면 부가기능이 서비스에 리소스를 만들고 이를 가리키는 URL을 생성해야 합니다.

부가기능은 생성된 리소스의 칩을 문서에 삽입합니다. 사용자가 이 칩 위로 포인터를 가져가면 부가기능의 연결된 링크 미리보기 트리거가 호출됩니다. 부가기능이 링크 미리보기 트리거에서 지원하는 링크 패턴이 있는 칩을 삽입하는지 확인합니다.

기본 요건

Apps Script

  • 사용자가 만드는 리소스의 링크 패턴에 대한 링크 미리보기를 지원하는 Google Workspace 부가기능입니다. 링크 미리보기가 있는 부가기능을 빌드하려면 스마트 칩을 사용한 링크 미리보기를 참고하세요.

Node.js

  • 사용자가 만드는 리소스의 링크 패턴에 대한 링크 미리보기를 지원하는 Google Workspace 부가기능입니다. 링크 미리보기가 있는 부가기능을 빌드하려면 스마트 칩을 사용한 링크 미리보기를 참고하세요.

Python

  • 사용자가 만드는 리소스의 링크 패턴에 대한 링크 미리보기를 지원하는 Google Workspace 부가기능입니다. 링크 미리보기가 있는 부가기능을 빌드하려면 스마트 칩을 사용한 링크 미리보기를 참고하세요.

자바

  • 사용자가 만드는 리소스의 링크 패턴에 대한 링크 미리보기를 지원하는 Google Workspace 부가기능입니다. 링크 미리보기가 있는 부가기능을 빌드하려면 스마트 칩을 사용한 링크 미리보기를 참고하세요.

부가기능의 리소스 생성 설정

이 섹션에서는 부가기능의 리소스 생성을 설정하는 방법을 설명합니다. 여기에는 다음 단계가 포함됩니다.

  1. 부가기능의 매니페스트에서 리소스 생성을 구성합니다.
  2. 사용자가 서비스 내에서 리소스를 만들 때 필요한 양식 카드를 빌드합니다.
  3. 사용자가 양식을 제출할 때 리소스를 만드는 함수가 실행되도록 양식 제출을 처리합니다.

리소스 생성 구성

리소스 생성을 구성하려면 부가기능 매니페스트에서 다음 섹션과 필드를 지정합니다.

  1. docs 필드의 addOns 섹션에서 runFunction가 포함된 createActionTriggers 트리거를 구현합니다. 이 함수는 다음 섹션인 양식 카드 빌드에서 정의합니다.

    createActionTriggers 트리거에서 지정할 수 있는 필드에 대해 알아보려면 Apps Script 매니페스트 또는 기타 런타임의 배포 리소스의 참고 문서를 참고하세요.

  2. 사용자가 리소스를 만들도록 부가기능을 승인할 수 있도록 oauthScopes 필드에 범위 https://www.googleapis.com/auth/workspace.linkcreate를 추가합니다. 특히 이 범위를 사용하면 부가기능이 사용자가 리소스 생성 양식에 제출한 정보를 읽고 이 정보를 기반으로 문서에 스마트 칩을 삽입할 수 있습니다.

예를 들어 다음 지원 케이스 서비스의 리소스 생성을 구성하는 매니페스트의 addons 섹션을 참고하세요.

{
  "oauthScopes": [
    "https://www.googleapis.com/auth/workspace.linkpreview",
    "https://www.googleapis.com/auth/workspace.linkcreate"
  ],
  "addOns": {
    "docs": {
      "linkPreviewTriggers": [
        ...
      ],
      "createActionTriggers": [
        {
          "id": "createCase",
          "labelText": "Create support case",
          "localizedLabelText": {
            "es": "Crear caso de soporte"
          },
          "runFunction": "createCaseInputCard",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    }
  }
}

이 예에서는 Google Workspace 부가기능을 통해 사용자가 지원 케이스를 만들 수 있습니다. 각 createActionTriggers 트리거에는 다음 필드가 있어야 합니다.

  • 고유 ID
  • Docs @ 메뉴에 표시되는 텍스트 라벨
  • @ 메뉴의 라벨 텍스트 옆에 표시되는 아이콘을 가리키는 로고 URL
  • 카드를 반환하는 Apps Script 함수 또는 HTTP 엔드포인트를 참조하는 콜백 함수

양식 카드 빌드

Docs @ 메뉴에서 서비스에 리소스를 만들려면 createActionTriggers 객체에 지정한 모든 함수를 구현해야 합니다.

사용자가 메뉴 항목 중 하나와 상호작용하면 해당 createActionTriggers 트리거가 실행되고 콜백 함수가 리소스 생성을 위한 양식 입력란이 있는 카드를 표시합니다.

지원되는 요소 및 작업

카드 인터페이스를 만들려면 위젯을 사용하여 사용자가 리소스를 만들 때 필요한 정보와 입력을 표시합니다. 대부분의 Google Workspace 부가기능 위젯과 작업은 다음 예외를 제외하고 지원됩니다.

  • 카드 바닥글은 지원되지 않습니다.
  • 알림은 지원되지 않습니다.
  • 탐색의 경우 updateCard 탐색만 지원됩니다.

양식 입력이 있는 카드의 예

다음 예는 사용자가 @ 메뉴에서 Create support case(지원 케이스 만들기)를 선택할 때 카드를 표시하는 Apps Script 콜백 함수를 보여줍니다.

Apps Script

apps-script/3p-resources/3p-resources.gs
/**
 * Produces a support case creation form card.
 * 
 * @param {!Object} event The event object.
 * @param {!Object=} errors An optional map of per-field error messages.
 * @param {boolean} isUpdate Whether to return the form as an update card navigation.
 * @return {!Card|!ActionResponse} The resulting card or action response.
 */
function createCaseInputCard(event, errors, isUpdate) {

  const cardHeader = CardService.newCardHeader()
    .setTitle('Create a support case')

  const cardSectionTextInput1 = CardService.newTextInput()
    .setFieldName('name')
    .setTitle('Name')
    .setMultiline(false);

  const cardSectionTextInput2 = CardService.newTextInput()
    .setFieldName('description')
    .setTitle('Description')
    .setMultiline(true);

  const cardSectionSelectionInput1 = CardService.newSelectionInput()
    .setFieldName('priority')
    .setTitle('Priority')
    .setType(CardService.SelectionInputType.DROPDOWN)
    .addItem('P0', 'P0', false)
    .addItem('P1', 'P1', false)
    .addItem('P2', 'P2', false)
    .addItem('P3', 'P3', false);

  const cardSectionSelectionInput2 = CardService.newSelectionInput()
    .setFieldName('impact')
    .setTitle('Impact')
    .setType(CardService.SelectionInputType.CHECK_BOX)
    .addItem('Blocks a critical customer operation', 'Blocks a critical customer operation', false);

  const cardSectionButtonListButtonAction = CardService.newAction()
    .setPersistValues(true)
    .setFunctionName('submitCaseCreationForm')
    .setParameters({});

  const cardSectionButtonListButton = CardService.newTextButton()
    .setText('Create')
    .setTextButtonStyle(CardService.TextButtonStyle.TEXT)
    .setOnClickAction(cardSectionButtonListButtonAction);

  const cardSectionButtonList = CardService.newButtonSet()
    .addButton(cardSectionButtonListButton);

  // Builds the form inputs with error texts for invalid values.
  const cardSection = CardService.newCardSection();
  if (errors?.name) {
    cardSection.addWidget(createErrorTextParagraph(errors.name));
  }
  cardSection.addWidget(cardSectionTextInput1);
  if (errors?.description) {
    cardSection.addWidget(createErrorTextParagraph(errors.description));
  }
  cardSection.addWidget(cardSectionTextInput2);
  if (errors?.priority) {
    cardSection.addWidget(createErrorTextParagraph(errors.priority));
  }
  cardSection.addWidget(cardSectionSelectionInput1);
  if (errors?.impact) {
    cardSection.addWidget(createErrorTextParagraph(errors.impact));
  }

  cardSection.addWidget(cardSectionSelectionInput2);
  cardSection.addWidget(cardSectionButtonList);

  const card = CardService.newCardBuilder()
    .setHeader(cardHeader)
    .addSection(cardSection)
    .build();

  if (isUpdate) {
    return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(card))
      .build();
  } else {
    return card;
  }
}

Node.js

node/3p-resources/index.js
/**
 * Produces a support case creation form card.
 * 
 * @param {!Object} event The event object.
 * @param {!Object=} errors An optional map of per-field error messages.
 * @param {boolean} isUpdate Whether to return the form as an update card navigation.
 * @return {!Card|!ActionResponse} The resulting card or action response.
 */
function createCaseInputCard(event, errors, isUpdate) {

  const cardHeader1 = {
    title: "Create a support case"
  };

  const cardSection1TextInput1 = {
    textInput: {
      name: "name",
      label: "Name"
    }
  };

  const cardSection1TextInput2 = {
    textInput: {
      name: "description",
      label: "Description",
      type: "MULTIPLE_LINE"
    }
  };

  const cardSection1SelectionInput1 = {
    selectionInput: {
      name: "priority",
      label: "Priority",
      type: "DROPDOWN",
      items: [{
        text: "P0",
        value: "P0"
      }, {
        text: "P1",
        value: "P1"
      }, {
        text: "P2",
        value: "P2"
      }, {
        text: "P3",
        value: "P3"
      }]
    }
  };

  const cardSection1SelectionInput2 = {
    selectionInput: {
      name: "impact",
      label: "Impact",
      items: [{
        text: "Blocks a critical customer operation",
        value: "Blocks a critical customer operation"
      }]
    }
  };

  const cardSection1ButtonList1Button1Action1 = {
    function: process.env.URL,
    parameters: [
      {
        key: "submitCaseCreationForm",
        value: true
      }
    ],
    persistValues: true
  };

  const cardSection1ButtonList1Button1 = {
    text: "Create",
    onClick: {
      action: cardSection1ButtonList1Button1Action1
    }
  };

  const cardSection1ButtonList1 = {
    buttonList: {
      buttons: [cardSection1ButtonList1Button1]
    }
  };

  // Builds the creation form and adds error text for invalid inputs.
  const cardSection1 = [];
  if (errors?.name) {
    cardSection1.push(createErrorTextParagraph(errors.name));
  }
  cardSection1.push(cardSection1TextInput1);
  if (errors?.description) {
    cardSection1.push(createErrorTextParagraph(errors.description));
  }
  cardSection1.push(cardSection1TextInput2);
  if (errors?.priority) {
    cardSection1.push(createErrorTextParagraph(errors.priority));
  }
  cardSection1.push(cardSection1SelectionInput1);
  if (errors?.impact) {
    cardSection1.push(createErrorTextParagraph(errors.impact));
  }

  cardSection1.push(cardSection1SelectionInput2);
  cardSection1.push(cardSection1ButtonList1);

  const card = {
    header: cardHeader1,
    sections: [{
      widgets: cardSection1
    }]
  };

  if (isUpdate) {
    return {
      renderActions: {
        action: {
          navigations: [{
            updateCard: card
          }]
        }
      }
    };
  } else {
    return {
      action: {
        navigations: [{
          pushCard: card
        }]
      }
    };
  }
}

Python

python/3p-resources/create_3p_resources/main.py
def create_case_input_card(event, errors = {}, isUpdate = False):
    """Produces a support case creation form card.
    Args:
      event: The event object.
      errors: An optional dict of per-field error messages.
      isUpdate: Whether to return the form as an update card navigation.
    Returns:
      The resulting card or action response.
    """
    card_header1 = {
        "title": "Create a support case"
    }

    card_section1_text_input1 = {
        "textInput": {
            "name": "name",
            "label": "Name"
        }
    }

    card_section1_text_input2 = {
        "textInput": {
            "name": "description",
            "label": "Description",
            "type": "MULTIPLE_LINE"
        }
    }

    card_section1_selection_input1 = {
        "selectionInput": {
            "name": "priority",
            "label": "Priority",
            "type": "DROPDOWN",
            "items": [{
                "text": "P0",
                "value": "P0"
            }, {
                "text": "P1",
                "value": "P1"
            }, {
                "text": "P2",
                "value": "P2"
            }, {
                "text": "P3",
                "value": "P3"
            }]
        }
    }

    card_section1_selection_input2 = {
        "selectionInput": {
            "name": "impact",
            "label": "Impact",
            "items": [{
                "text": "Blocks a critical customer operation",
                "value": "Blocks a critical customer operation"
            }]
        }
    }

    card_section1_button_list1_button1_action1 = {
        "function": os.environ["URL"],
        "parameters": [
        {
            "key": "submitCaseCreationForm",
            "value": True
        }
        ],
        "persistValues": True
    }

    card_section1_button_list1_button1 = {
        "text": "Create",
        "onClick": {
            "action": card_section1_button_list1_button1_action1
        }
    }

    card_section1_button_list1 = {
        "buttonList": {
            "buttons": [card_section1_button_list1_button1]
        }
    }

    # Builds the creation form and adds error text for invalid inputs.
    card_section1 = []
    if "name" in errors:
        card_section1.append(create_error_text_paragraph(errors["name"]))
    card_section1.append(card_section1_text_input1)
    if "description" in errors:
        card_section1.append(create_error_text_paragraph(errors["description"]))
    card_section1.append(card_section1_text_input2)
    if "priority" in errors:
        card_section1.append(create_error_text_paragraph(errors["priority"]))
    card_section1.append(card_section1_selection_input1)
    if "impact" in errors:
        card_section1.append(create_error_text_paragraph(errors["impact"]))

    card_section1.append(card_section1_selection_input2)
    card_section1.append(card_section1_button_list1)

    card = {
        "header": card_header1,
        "sections": [{
            "widgets": card_section1
        }]
    }

    if isUpdate:
        return {
            "renderActions": {
                "action": {
                        "navigations": [{
                        "updateCard": card
                    }]
                }
            }
        }
    else:
        return {
            "action": {
                "navigations": [{
                    "pushCard": card
                }]
            }
        }

자바

java/3p-resources/src/main/java/Create3pResources.java
/**
 * Produces a support case creation form.
 * 
 * @param event The event object.
 * @param errors A map of per-field error messages.
 * @param isUpdate Whether to return the form as an update card navigation.
 * @return The resulting card or action response.
 */
JsonObject createCaseInputCard(JsonObject event, Map<String, String> errors, boolean isUpdate) {
  JsonObject cardHeader = new JsonObject();
  cardHeader.add("title", new JsonPrimitive("Create a support case"));

  JsonObject cardSectionTextInput1 = new JsonObject();
  cardSectionTextInput1.add("name", new JsonPrimitive("name"));
  cardSectionTextInput1.add("label", new JsonPrimitive("Name"));

  JsonObject cardSectionTextInput1Widget = new JsonObject();
  cardSectionTextInput1Widget.add("textInput", cardSectionTextInput1);

  JsonObject cardSectionTextInput2 = new JsonObject();
  cardSectionTextInput2.add("name", new JsonPrimitive("description"));
  cardSectionTextInput2.add("label", new JsonPrimitive("Description"));
  cardSectionTextInput2.add("type", new JsonPrimitive("MULTIPLE_LINE"));

  JsonObject cardSectionTextInput2Widget = new JsonObject();
  cardSectionTextInput2Widget.add("textInput", cardSectionTextInput2);

  JsonObject cardSectionSelectionInput1ItemsItem1 = new JsonObject();
  cardSectionSelectionInput1ItemsItem1.add("text", new JsonPrimitive("P0"));
  cardSectionSelectionInput1ItemsItem1.add("value", new JsonPrimitive("P0"));

  JsonObject cardSectionSelectionInput1ItemsItem2 = new JsonObject();
  cardSectionSelectionInput1ItemsItem2.add("text", new JsonPrimitive("P1"));
  cardSectionSelectionInput1ItemsItem2.add("value", new JsonPrimitive("P1"));

  JsonObject cardSectionSelectionInput1ItemsItem3 = new JsonObject();
  cardSectionSelectionInput1ItemsItem3.add("text", new JsonPrimitive("P2"));
  cardSectionSelectionInput1ItemsItem3.add("value", new JsonPrimitive("P2"));

  JsonObject cardSectionSelectionInput1ItemsItem4 = new JsonObject();
  cardSectionSelectionInput1ItemsItem4.add("text", new JsonPrimitive("P3"));
  cardSectionSelectionInput1ItemsItem4.add("value", new JsonPrimitive("P3"));

  JsonArray cardSectionSelectionInput1Items = new JsonArray();
  cardSectionSelectionInput1Items.add(cardSectionSelectionInput1ItemsItem1);
  cardSectionSelectionInput1Items.add(cardSectionSelectionInput1ItemsItem2);
  cardSectionSelectionInput1Items.add(cardSectionSelectionInput1ItemsItem3);
  cardSectionSelectionInput1Items.add(cardSectionSelectionInput1ItemsItem4);

  JsonObject cardSectionSelectionInput1 = new JsonObject();
  cardSectionSelectionInput1.add("name", new JsonPrimitive("priority"));
  cardSectionSelectionInput1.add("label", new JsonPrimitive("Priority"));
  cardSectionSelectionInput1.add("type", new JsonPrimitive("DROPDOWN"));
  cardSectionSelectionInput1.add("items", cardSectionSelectionInput1Items);

  JsonObject cardSectionSelectionInput1Widget = new JsonObject();
  cardSectionSelectionInput1Widget.add("selectionInput", cardSectionSelectionInput1);

  JsonObject cardSectionSelectionInput2ItemsItem = new JsonObject();
  cardSectionSelectionInput2ItemsItem.add("text", new JsonPrimitive("Blocks a critical customer operation"));
  cardSectionSelectionInput2ItemsItem.add("value", new JsonPrimitive("Blocks a critical customer operation"));

  JsonArray cardSectionSelectionInput2Items = new JsonArray();
  cardSectionSelectionInput2Items.add(cardSectionSelectionInput2ItemsItem);

  JsonObject cardSectionSelectionInput2 = new JsonObject();
  cardSectionSelectionInput2.add("name", new JsonPrimitive("impact"));
  cardSectionSelectionInput2.add("label", new JsonPrimitive("Impact"));
  cardSectionSelectionInput2.add("items", cardSectionSelectionInput2Items);

  JsonObject cardSectionSelectionInput2Widget = new JsonObject();
  cardSectionSelectionInput2Widget.add("selectionInput", cardSectionSelectionInput2);

  JsonObject cardSectionButtonListButtonActionParametersParameter = new JsonObject();
  cardSectionButtonListButtonActionParametersParameter.add("key", new JsonPrimitive("submitCaseCreationForm"));
  cardSectionButtonListButtonActionParametersParameter.add("value", new JsonPrimitive(true));

  JsonArray cardSectionButtonListButtonActionParameters = new JsonArray();
  cardSectionButtonListButtonActionParameters.add(cardSectionButtonListButtonActionParametersParameter);

  JsonObject cardSectionButtonListButtonAction = new JsonObject();
  cardSectionButtonListButtonAction.add("function", new JsonPrimitive(System.getenv().get("URL")));
  cardSectionButtonListButtonAction.add("parameters", cardSectionButtonListButtonActionParameters);
  cardSectionButtonListButtonAction.add("persistValues", new JsonPrimitive(true));

  JsonObject cardSectionButtonListButtonOnCLick = new JsonObject();
  cardSectionButtonListButtonOnCLick.add("action", cardSectionButtonListButtonAction);

  JsonObject cardSectionButtonListButton = new JsonObject();
  cardSectionButtonListButton.add("text", new JsonPrimitive("Create"));
  cardSectionButtonListButton.add("onClick", cardSectionButtonListButtonOnCLick);

  JsonArray cardSectionButtonListButtons = new JsonArray();
  cardSectionButtonListButtons.add(cardSectionButtonListButton);

  JsonObject cardSectionButtonList = new JsonObject();
  cardSectionButtonList.add("buttons", cardSectionButtonListButtons);

  JsonObject cardSectionButtonListWidget = new JsonObject();
  cardSectionButtonListWidget.add("buttonList", cardSectionButtonList);

  // Builds the form inputs with error texts for invalid values.
  JsonArray cardSection = new JsonArray();
  if (errors.containsKey("name")) {
    cardSection.add(createErrorTextParagraph(errors.get("name").toString()));
  }
  cardSection.add(cardSectionTextInput1Widget);
  if (errors.containsKey("description")) {
    cardSection.add(createErrorTextParagraph(errors.get("description").toString()));
  }
  cardSection.add(cardSectionTextInput2Widget);
  if (errors.containsKey("priority")) {
    cardSection.add(createErrorTextParagraph(errors.get("priority").toString()));
  }
  cardSection.add(cardSectionSelectionInput1Widget);
  if (errors.containsKey("impact")) {
    cardSection.add(createErrorTextParagraph(errors.get("impact").toString()));
  }

  cardSection.add(cardSectionSelectionInput2Widget);
  cardSection.add(cardSectionButtonListWidget);

  JsonObject cardSectionWidgets = new JsonObject();
  cardSectionWidgets.add("widgets", cardSection);

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

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

  JsonObject navigation = new JsonObject();
  if (isUpdate) {
    navigation.add("updateCard", card);
  } else {
    navigation.add("pushCard", card);
  }

  JsonArray navigations = new JsonArray();
  navigations.add(navigation);

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

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

  if (!isUpdate) {
    return renderActions;
  }

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

  return update;
}

createCaseInputCard 함수는 다음 카드를 렌더링합니다.

양식 입력란이 있는 카드

카드에는 텍스트 입력란, 드롭다운 메뉴, 체크박스가 포함되어 있습니다. 또한 생성 양식 제출을 처리하는 다른 함수를 실행하는 onClick 작업이 있는 텍스트 버튼이 있습니다.

사용자가 양식을 작성하고 만들기를 클릭하면 부가기능이 양식 입력을 onClick 작업 함수(이 예에서는 submitCaseCreationForm라고 함)에 전송합니다. 이때 부가기능은 입력의 유효성을 검사하고 이를 사용하여 서드 파티 서비스에서 리소스를 만들 수 있습니다.

양식 제출 처리

사용자가 생성 양식을 제출하면 onClick 작업과 연결된 함수가 실행됩니다. 이상적인 사용자 환경을 제공하려면 부가기능이 양식 제출 성공 여부와 관계없이 양식 제출을 모두 처리해야 합니다.

리소스 생성 완료 처리

부가기능의 onClick 함수는 서드 파티 서비스에 리소스를 만들고 이를 가리키는 URL을 생성해야 합니다.

칩을 만들기 위해 Docs에 리소스의 URL을 다시 전달하려면 onClick 함수가 renderActions.action.links에 링크를 가리키는 1개 요소 배열이 있는 SubmitFormResponse를 반환해야 합니다. 링크 제목은 생성된 리소스의 제목을 나타내야 하며 URL은 해당 리소스를 가리켜야 합니다.

다음 예는 생성된 리소스의 SubmitFormResponse를 보여줍니다.

Apps Script

apps-script/3p-resources/3p-resources.gs
/**
 * Returns a submit form response that inserts a link into the document.
 * 
 * @param {string} title The title of the link to insert.
 * @param {string} url The URL of the link to insert.
 * @return {!SubmitFormResponse} The resulting submit form response.
 */
function createLinkRenderAction(title, url) {
  return {
    renderActions: {
      action: {
        links: [{
          title: title,
          url: url
        }]
      }
    }
  };
}

Node.js

node/3p-resources/index.js
/**
 * Returns a submit form response that inserts a link into the document.
 * 
 * @param {string} title The title of the link to insert.
 * @param {string} url The URL of the link to insert.
 * @return {!SubmitFormResponse} The resulting submit form response.
 */
function createLinkRenderAction(title, url) {
  return {
    renderActions: {
      action: {
        links: [{
          title: title,
          url: url
        }]
      }
    }
  };
}

Python

python/3p-resources/create_3p_resources/main.py
def create_link_render_action(title, url):
    """Returns a submit form response that inserts a link into the document.
    Args:
      title: The title of the link to insert.
      url: The URL of the link to insert.
    Returns:
      The resulting submit form response.
    """
    return {
        "renderActions": {
            "action": {
                "links": [{
                    "title": title,
                    "url": url
                }]
            }
        }
    }

자바

java/3p-resources/src/main/java/Create3pResources.java
/**
 * Returns a submit form response that inserts a link into the document.
 * 
 * @param title The title of the link to insert.
 * @param url The URL of the link to insert.
 * @return The resulting submit form response.
 */
JsonObject createLinkRenderAction(String title, String url) {
  JsonObject link = new JsonObject();
  link.add("title", new JsonPrimitive(title));
  link.add("url", new JsonPrimitive(url));

  JsonArray links = new JsonArray();
  links.add(link);

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

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

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

  return linkRenderAction;
}

SubmitFormResponse가 반환되면 모달 대화상자가 닫히고 부가기능이 문서에 칩을 삽입합니다. 사용자가 이 칩 위로 포인터를 가져가면 연결된 링크 미리보기 트리거가 호출됩니다. 링크 미리보기 트리거에서 지원하지 않는 링크 패턴이 있는 칩이 부가기능에 삽입되지 않도록 합니다.

오류 처리

사용자가 잘못된 입력란이 있는 양식을 제출하려고 하면 부가기능은 링크가 있는 SubmitFormResponse를 반환하는 대신 updateCard 탐색을 사용하여 오류를 표시하는 렌더링 작업을 반환해야 합니다. 이렇게 하면 사용자가 잘못한 부분을 확인하고 다시 시도할 수 있습니다. Apps Script의 경우 updateCard(card)를, 기타 런타임의 경우 updateCard를 참고하세요. 알림 및 pushCard 탐색은 지원되지 않습니다.

오류 처리 예시

다음 예는 사용자가 양식을 제출할 때 호출되는 코드를 보여줍니다. 입력이 유효하지 않으면 카드가 업데이트되고 오류 메시지가 표시됩니다. 입력이 유효하면 부가기능은 생성된 리소스의 링크가 포함된 SubmitFormResponse를 반환합니다.

Apps Script

apps-script/3p-resources/3p-resources.gs
/**
 * Submits the creation form. If valid, returns a render action
 * that inserts a new link into the document. If invalid, returns an
 * update card navigation that re-renders the creation form with error messages.
 * 
 * @param {!Object} event The event object with form input values.
 * @return {!ActionResponse|!SubmitFormResponse} The resulting response.
 */
function submitCaseCreationForm(event) {
  const caseDetails = {
    name: event.formInput.name,
    description: event.formInput.description,
    priority: event.formInput.priority,
    impact: !!event.formInput.impact,
  };

  const errors = validateFormInputs(caseDetails);
  if (Object.keys(errors).length > 0) {
    return createCaseInputCard(event, errors, /* isUpdate= */ true);
  } else {
    const title = `Case ${caseDetails.name}`;
    // Adds the case details as parameters to the generated link URL.
    const url = 'https://example.com/support/cases/?' + generateQuery(caseDetails);
    return createLinkRenderAction(title, url);
  }
}

/**
* Build a query path with URL parameters.
*
* @param {!Map} parameters A map with the URL parameters.
* @return {!string} The resulting query path.
*/
function generateQuery(parameters) {
  return Object.entries(parameters).flatMap(([k, v]) =>
    Array.isArray(v) ? v.map(e => `${k}=${encodeURIComponent(e)}`) : `${k}=${encodeURIComponent(v)}`
  ).join("&");
}

Node.js

node/3p-resources/index.js
/**
 * Submits the creation form. If valid, returns a render action
 * that inserts a new link into the document. If invalid, returns an
 * update card navigation that re-renders the creation form with error messages.
 * 
 * @param {!Object} event The event object with form input values.
 * @return {!ActionResponse|!SubmitFormResponse} The resulting response.
 */
function submitCaseCreationForm(event) {
  const caseDetails = {
    name: event.commonEventObject.formInputs?.name?.stringInputs?.value[0],
    description: event.commonEventObject.formInputs?.description?.stringInputs?.value[0],
    priority: event.commonEventObject.formInputs?.priority?.stringInputs?.value[0],
    impact: !!event.commonEventObject.formInputs?.impact?.stringInputs?.value[0],
  };

  const errors = validateFormInputs(caseDetails);
  if (Object.keys(errors).length > 0) {
    return createCaseInputCard(event, errors, /* isUpdate= */ true);
  } else {
    const title = `Case ${caseDetails.name}`;
    // Adds the case details as parameters to the generated link URL.
    const url = new URL('https://example.com/support/cases/');
    for (const [key, value] of Object.entries(caseDetails)) {
      url.searchParams.append(key, value);
    }
    return createLinkRenderAction(title, url.href);
  }
}

Python

python/3p-resources/create_3p_resources/main.py
def submit_case_creation_form(event):
    """Submits the creation form.

    If valid, returns a render action that inserts a new link
    into the document. If invalid, returns an update card navigation that
    re-renders the creation form with error messages.
    Args:
      event: The event object with form input values.
    Returns:
      The resulting response.
    """
    formInputs = event["commonEventObject"]["formInputs"] if "formInputs" in event["commonEventObject"] else None
    case_details = {
        "name":  None,
        "description": None,
        "priority": None,
        "impact": None,
    }
    if formInputs is not None:
        case_details["name"] = formInputs["name"]["stringInputs"]["value"][0] if "name" in formInputs else None
        case_details["description"] = formInputs["description"]["stringInputs"]["value"][0] if "description" in formInputs else None
        case_details["priority"] = formInputs["priority"]["stringInputs"]["value"][0] if "priority" in formInputs else None
        case_details["impact"] = formInputs["impact"]["stringInputs"]["value"][0] if "impact" in formInputs else False

    errors = validate_form_inputs(case_details)
    if len(errors) > 0:
        return create_case_input_card(event, errors, True) # Update mode
    else:
        title = f'Case {case_details["name"]}'
        # Adds the case details as parameters to the generated link URL.
        url = "https://example.com/support/cases/?" + urlencode(case_details)
        return create_link_render_action(title, url)

자바

java/3p-resources/src/main/java/Create3pResources.java
/**
 * Submits the creation form. If valid, returns a render action
 * that inserts a new link into the document. If invalid, returns an
 * update card navigation that re-renders the creation form with error messages.
 * 
 * @param event The event object with form input values.
 * @return The resulting response.
 */
JsonObject submitCaseCreationForm(JsonObject event) throws Exception {
  JsonObject formInputs = event.getAsJsonObject("commonEventObject").getAsJsonObject("formInputs");
  Map<String, String> caseDetails = new HashMap<String, String>();
  if (formInputs != null) {
    if (formInputs.has("name")) {
      caseDetails.put("name", formInputs.getAsJsonObject("name").getAsJsonObject("stringInputs").getAsJsonArray("value").get(0).getAsString());
    }
    if (formInputs.has("description")) {
      caseDetails.put("description", formInputs.getAsJsonObject("description").getAsJsonObject("stringInputs").getAsJsonArray("value").get(0).getAsString());
    }
    if (formInputs.has("priority")) {
      caseDetails.put("priority", formInputs.getAsJsonObject("priority").getAsJsonObject("stringInputs").getAsJsonArray("value").get(0).getAsString());
    }
    if (formInputs.has("impact")) {
      caseDetails.put("impact", formInputs.getAsJsonObject("impact").getAsJsonObject("stringInputs").getAsJsonArray("value").get(0).getAsString());
    }
  }

  Map<String, String> errors = validateFormInputs(caseDetails);
  if (errors.size() > 0) {
    return createCaseInputCard(event, errors, /* isUpdate= */ true);
  } else {
    String title = String.format("Case %s", caseDetails.get("name"));
    // Adds the case details as parameters to the generated link URL.
    URIBuilder uriBuilder = new URIBuilder("https://example.com/support/cases/");
    for (String caseDetailKey : caseDetails.keySet()) {
      uriBuilder.addParameter(caseDetailKey, caseDetails.get(caseDetailKey));
    }
    return createLinkRenderAction(title, uriBuilder.build().toURL().toString());
  }
}

다음 코드 샘플은 양식 입력을 검사하고 잘못된 입력에 관한 오류 메시지를 만듭니다.

Apps Script

apps-script/3p-resources/3p-resources.gs
/**
 * Validates case creation form input values.
 * 
 * @param {!Object} caseDetails The values of each form input submitted by the user.
 * @return {!Object} A map from field name to error message. An empty object
 *     represents a valid form submission.
 */
function validateFormInputs(caseDetails) {
  const errors = {};
  if (!caseDetails.name) {
    errors.name = 'You must provide a name';
  }
  if (!caseDetails.description) {
    errors.description = 'You must provide a description';
  }
  if (!caseDetails.priority) {
    errors.priority = 'You must provide a priority';
  }
  if (caseDetails.impact && caseDetails.priority !== 'P0' && caseDetails.priority !== 'P1') {
    errors.impact = 'If an issue blocks a critical customer operation, priority must be P0 or P1';
  }

  return errors;
}

/**
 * Returns a text paragraph with red text indicating a form field validation error.
 * 
 * @param {string} errorMessage A description of input value error.
 * @return {!TextParagraph} The resulting text paragraph.
 */
function createErrorTextParagraph(errorMessage) {
  return CardService.newTextParagraph()
    .setText('<font color=\"#BA0300\"><b>Error:</b> ' + errorMessage + '</font>');
}

Node.js

node/3p-resources/index.js
/**
 * Validates case creation form input values.
 * 
 * @param {!Object} caseDetails The values of each form input submitted by the user.
 * @return {!Object} A map from field name to error message. An empty object
 *     represents a valid form submission.
 */
function validateFormInputs(caseDetails) {
  const errors = {};
  if (caseDetails.name === undefined) {
    errors.name = 'You must provide a name';
  }
  if (caseDetails.description === undefined) {
    errors.description = 'You must provide a description';
  }
  if (caseDetails.priority === undefined) {
    errors.priority = 'You must provide a priority';
  }
  if (caseDetails.impact && !(['P0', 'P1']).includes(caseDetails.priority)) {
    errors.impact = 'If an issue blocks a critical customer operation, priority must be P0 or P1';
  }

  return errors;
}

/**
 * Returns a text paragraph with red text indicating a form field validation error.
 * 
 * @param {string} errorMessage A description of input value error.
 * @return {!TextParagraph} The resulting text paragraph.
 */
function createErrorTextParagraph(errorMessage) {
  return {
    textParagraph: {
      text: '<font color=\"#BA0300\"><b>Error:</b> ' + errorMessage + '</font>'
    }
  }
}

Python

python/3p-resources/create_3p_resources/main.py
def validate_form_inputs(case_details):
    """Validates case creation form input values.
    Args:
      case_details: The values of each form input submitted by the user.
    Returns:
      A dict from field name to error message. An empty object represents a valid form submission.
    """
    errors = {}
    if case_details["name"] is None:
        errors["name"] = "You must provide a name"
    if case_details["description"] is None:
        errors["description"] = "You must provide a description"
    if case_details["priority"] is None:
        errors["priority"] = "You must provide a priority"
    if case_details["impact"] is not None and case_details["priority"] not in ['P0', 'P1']:
        errors["impact"] = "If an issue blocks a critical customer operation, priority must be P0 or P1"
    return errors


def create_error_text_paragraph(error_message):
    """Returns a text paragraph with red text indicating a form field validation error.
    Args:
      error_essage: A description of input value error.
    Returns:
      The resulting text paragraph.
    """
    return {
        "textParagraph": {
            "text": '<font color=\"#BA0300\"><b>Error:</b> ' + error_message + '</font>'
        }
    }

자바

java/3p-resources/src/main/java/Create3pResources.java
/**
 * Validates case creation form input values.
 * 
 * @param caseDetails The values of each form input submitted by the user.
 * @return A map from field name to error message. An empty object
 *     represents a valid form submission.
 */
Map<String, String> validateFormInputs(Map<String, String> caseDetails) {
  Map<String, String> errors = new HashMap<String, String>();
  if (!caseDetails.containsKey("name")) {
    errors.put("name", "You must provide a name");
  }
  if (!caseDetails.containsKey("description")) {
    errors.put("description", "You must provide a description");
  }
  if (!caseDetails.containsKey("priority")) {
    errors.put("priority", "You must provide a priority");
  }
  if (caseDetails.containsKey("impact") && !Arrays.asList(new String[]{"P0", "P1"}).contains(caseDetails.get("priority"))) {
    errors.put("impact", "If an issue blocks a critical customer operation, priority must be P0 or P1");
  }

  return errors;
}

/**
 * Returns a text paragraph with red text indicating a form field validation error.
 * 
 * @param errorMessage A description of input value error.
 * @return The resulting text paragraph.
 */
JsonObject createErrorTextParagraph(String errorMessage) {
  JsonObject textParagraph = new JsonObject();
  textParagraph.add("text", new JsonPrimitive("<font color=\"#BA0300\"><b>Error:</b> " + errorMessage + "</font>"));

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

  return textParagraphWidget;
}

전체 예시: 지원 케이스 부가기능

다음 예는 회사의 지원 케이스에 대한 링크를 미리 보고 사용자가 Google Docs 내에서 지원 케이스를 만들 수 있는 Google Workspace 부가기능을 보여줍니다.

이 예시는 다음을 수행합니다.

  • Docs @ 메뉴에서 지원 케이스를 만들기 위한 양식 필드가 포함된 카드를 생성합니다.
  • 양식 입력을 검사하고 잘못된 입력의 경우 오류 메시지를 반환합니다.
  • 생성된 지원 케이스의 이름과 링크를 Docs 문서에 스마트 칩으로 삽입합니다.
  • 지원 케이스의 링크를 미리 봅니다(예: https://www.example.com/support/cases/1234). 스마트 칩에는 아이콘이 표시되고 미리보기 카드에는 케이스 이름, 우선순위, 설명이 포함됩니다.

매니페스트

Apps Script

apps-script/3p-resources/appsscript.json
{
  "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"
        }
      ]
    }
  }
}

Node.js

node/3p-resources/deployment.json
{
  "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": "$URL1",
          "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": "$URL2",
          "logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
        }
      ]
    }
  }
}

코드

Apps Script

apps-script/3p-resources/3p-resources.gs
/**
 * Copyright 2024 Google LLC
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *     https://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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



/**
 * Produces a support case creation form card.
 * 
 * @param {!Object} event The event object.
 * @param {!Object=} errors An optional map of per-field error messages.
 * @param {boolean} isUpdate Whether to return the form as an update card navigation.
 * @return {!Card|!ActionResponse} The resulting card or action response.
 */
function createCaseInputCard(event, errors, isUpdate) {

  const cardHeader = CardService.newCardHeader()
    .setTitle('Create a support case')

  const cardSectionTextInput1 = CardService.newTextInput()
    .setFieldName('name')
    .setTitle('Name')
    .setMultiline(false);

  const cardSectionTextInput2 = CardService.newTextInput()
    .setFieldName('description')
    .setTitle('Description')
    .setMultiline(true);

  const cardSectionSelectionInput1 = CardService.newSelectionInput()
    .setFieldName('priority')
    .setTitle('Priority')
    .setType(CardService.SelectionInputType.DROPDOWN)
    .addItem('P0', 'P0', false)
    .addItem('P1', 'P1', false)
    .addItem('P2', 'P2', false)
    .addItem('P3', 'P3', false);

  const cardSectionSelectionInput2 = CardService.newSelectionInput()
    .setFieldName('impact')
    .setTitle('Impact')
    .setType(CardService.SelectionInputType.CHECK_BOX)
    .addItem('Blocks a critical customer operation', 'Blocks a critical customer operation', false);

  const cardSectionButtonListButtonAction = CardService.newAction()
    .setPersistValues(true)
    .setFunctionName('submitCaseCreationForm')
    .setParameters({});

  const cardSectionButtonListButton = CardService.newTextButton()
    .setText('Create')
    .setTextButtonStyle(CardService.TextButtonStyle.TEXT)
    .setOnClickAction(cardSectionButtonListButtonAction);

  const cardSectionButtonList = CardService.newButtonSet()
    .addButton(cardSectionButtonListButton);

  // Builds the form inputs with error texts for invalid values.
  const cardSection = CardService.newCardSection();
  if (errors?.name) {
    cardSection.addWidget(createErrorTextParagraph(errors.name));
  }
  cardSection.addWidget(cardSectionTextInput1);
  if (errors?.description) {
    cardSection.addWidget(createErrorTextParagraph(errors.description));
  }
  cardSection.addWidget(cardSectionTextInput2);
  if (errors?.priority) {
    cardSection.addWidget(createErrorTextParagraph(errors.priority));
  }
  cardSection.addWidget(cardSectionSelectionInput1);
  if (errors?.impact) {
    cardSection.addWidget(createErrorTextParagraph(errors.impact));
  }

  cardSection.addWidget(cardSectionSelectionInput2);
  cardSection.addWidget(cardSectionButtonList);

  const card = CardService.newCardBuilder()
    .setHeader(cardHeader)
    .addSection(cardSection)
    .build();

  if (isUpdate) {
    return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(card))
      .build();
  } else {
    return card;
  }
}


/**
 * Submits the creation form. If valid, returns a render action
 * that inserts a new link into the document. If invalid, returns an
 * update card navigation that re-renders the creation form with error messages.
 * 
 * @param {!Object} event The event object with form input values.
 * @return {!ActionResponse|!SubmitFormResponse} The resulting response.
 */
function submitCaseCreationForm(event) {
  const caseDetails = {
    name: event.formInput.name,
    description: event.formInput.description,
    priority: event.formInput.priority,
    impact: !!event.formInput.impact,
  };

  const errors = validateFormInputs(caseDetails);
  if (Object.keys(errors).length > 0) {
    return createCaseInputCard(event, errors, /* isUpdate= */ true);
  } else {
    const title = `Case ${caseDetails.name}`;
    // Adds the case details as parameters to the generated link URL.
    const url = 'https://example.com/support/cases/?' + generateQuery(caseDetails);
    return createLinkRenderAction(title, url);
  }
}

/**
* Build a query path with URL parameters.
*
* @param {!Map} parameters A map with the URL parameters.
* @return {!string} The resulting query path.
*/
function generateQuery(parameters) {
  return Object.entries(parameters).flatMap(([k, v]) =>
    Array.isArray(v) ? v.map(e => `${k}=${encodeURIComponent(e)}`) : `${k}=${encodeURIComponent(v)}`
  ).join("&");
}


/**
 * Validates case creation form input values.
 * 
 * @param {!Object} caseDetails The values of each form input submitted by the user.
 * @return {!Object} A map from field name to error message. An empty object
 *     represents a valid form submission.
 */
function validateFormInputs(caseDetails) {
  const errors = {};
  if (!caseDetails.name) {
    errors.name = 'You must provide a name';
  }
  if (!caseDetails.description) {
    errors.description = 'You must provide a description';
  }
  if (!caseDetails.priority) {
    errors.priority = 'You must provide a priority';
  }
  if (caseDetails.impact && caseDetails.priority !== 'P0' && caseDetails.priority !== 'P1') {
    errors.impact = 'If an issue blocks a critical customer operation, priority must be P0 or P1';
  }

  return errors;
}

/**
 * Returns a text paragraph with red text indicating a form field validation error.
 * 
 * @param {string} errorMessage A description of input value error.
 * @return {!TextParagraph} The resulting text paragraph.
 */
function createErrorTextParagraph(errorMessage) {
  return CardService.newTextParagraph()
    .setText('<font color=\"#BA0300\"><b>Error:</b> ' + errorMessage + '</font>');
}


/**
 * Returns a submit form response that inserts a link into the document.
 * 
 * @param {string} title The title of the link to insert.
 * @param {string} url The URL of the link to insert.
 * @return {!SubmitFormResponse} The resulting submit form response.
 */
function createLinkRenderAction(title, url) {
  return {
    renderActions: {
      action: {
        links: [{
          title: title,
          url: url
        }]
      }
    }
  };
}

Node.js

node/3p-resources/index.js
/**
 * Copyright 2024 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * 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")
              }
            }]
          }]
        }
      }
    }
  };
}



/**
 * Responds to any HTTP request related to 3P resource creations.
 *
 * @param {Object} req An HTTP request context.
 * @param {Object} res An HTTP response context.
 */
exports.create3pResources = (req, res) => {
  const event = req.body;
  if (event.commonEventObject.parameters?.submitCaseCreationForm) {
    res.json(submitCaseCreationForm(event));
  } else {
    res.json(createCaseInputCard(event));
  }
};


/**
 * Produces a support case creation form card.
 * 
 * @param {!Object} event The event object.
 * @param {!Object=} errors An optional map of per-field error messages.
 * @param {boolean} isUpdate Whether to return the form as an update card navigation.
 * @return {!Card|!ActionResponse} The resulting card or action response.
 */
function createCaseInputCard(event, errors, isUpdate) {

  const cardHeader1 = {
    title: "Create a support case"
  };

  const cardSection1TextInput1 = {
    textInput: {
      name: "name",
      label: "Name"
    }
  };

  const cardSection1TextInput2 = {
    textInput: {
      name: "description",
      label: "Description",
      type: "MULTIPLE_LINE"
    }
  };

  const cardSection1SelectionInput1 = {
    selectionInput: {
      name: "priority",
      label: "Priority",
      type: "DROPDOWN",
      items: [{
        text: "P0",
        value: "P0"
      }, {
        text: "P1",
        value: "P1"
      }, {
        text: "P2",
        value: "P2"
      }, {
        text: "P3",
        value: "P3"
      }]
    }
  };

  const cardSection1SelectionInput2 = {
    selectionInput: {
      name: "impact",
      label: "Impact",
      items: [{
        text: "Blocks a critical customer operation",
        value: "Blocks a critical customer operation"
      }]
    }
  };

  const cardSection1ButtonList1Button1Action1 = {
    function: process.env.URL,
    parameters: [
      {
        key: "submitCaseCreationForm",
        value: true
      }
    ],
    persistValues: true
  };

  const cardSection1ButtonList1Button1 = {
    text: "Create",
    onClick: {
      action: cardSection1ButtonList1Button1Action1
    }
  };

  const cardSection1ButtonList1 = {
    buttonList: {
      buttons: [cardSection1ButtonList1Button1]
    }
  };

  // Builds the creation form and adds error text for invalid inputs.
  const cardSection1 = [];
  if (errors?.name) {
    cardSection1.push(createErrorTextParagraph(errors.name));
  }
  cardSection1.push(cardSection1TextInput1);
  if (errors?.description) {
    cardSection1.push(createErrorTextParagraph(errors.description));
  }
  cardSection1.push(cardSection1TextInput2);
  if (errors?.priority) {
    cardSection1.push(createErrorTextParagraph(errors.priority));
  }
  cardSection1.push(cardSection1SelectionInput1);
  if (errors?.impact) {
    cardSection1.push(createErrorTextParagraph(errors.impact));
  }

  cardSection1.push(cardSection1SelectionInput2);
  cardSection1.push(cardSection1ButtonList1);

  const card = {
    header: cardHeader1,
    sections: [{
      widgets: cardSection1
    }]
  };

  if (isUpdate) {
    return {
      renderActions: {
        action: {
          navigations: [{
            updateCard: card
          }]
        }
      }
    };
  } else {
    return {
      action: {
        navigations: [{
          pushCard: card
        }]
      }
    };
  }
}


/**
 * Submits the creation form. If valid, returns a render action
 * that inserts a new link into the document. If invalid, returns an
 * update card navigation that re-renders the creation form with error messages.
 * 
 * @param {!Object} event The event object with form input values.
 * @return {!ActionResponse|!SubmitFormResponse} The resulting response.
 */
function submitCaseCreationForm(event) {
  const caseDetails = {
    name: event.commonEventObject.formInputs?.name?.stringInputs?.value[0],
    description: event.commonEventObject.formInputs?.description?.stringInputs?.value[0],
    priority: event.commonEventObject.formInputs?.priority?.stringInputs?.value[0],
    impact: !!event.commonEventObject.formInputs?.impact?.stringInputs?.value[0],
  };

  const errors = validateFormInputs(caseDetails);
  if (Object.keys(errors).length > 0) {
    return createCaseInputCard(event, errors, /* isUpdate= */ true);
  } else {
    const title = `Case ${caseDetails.name}`;
    // Adds the case details as parameters to the generated link URL.
    const url = new URL('https://example.com/support/cases/');
    for (const [key, value] of Object.entries(caseDetails)) {
      url.searchParams.append(key, value);
    }
    return createLinkRenderAction(title, url.href);
  }
}


/**
 * Validates case creation form input values.
 * 
 * @param {!Object} caseDetails The values of each form input submitted by the user.
 * @return {!Object} A map from field name to error message. An empty object
 *     represents a valid form submission.
 */
function validateFormInputs(caseDetails) {
  const errors = {};
  if (caseDetails.name === undefined) {
    errors.name = 'You must provide a name';
  }
  if (caseDetails.description === undefined) {
    errors.description = 'You must provide a description';
  }
  if (caseDetails.priority === undefined) {
    errors.priority = 'You must provide a priority';
  }
  if (caseDetails.impact && !(['P0', 'P1']).includes(caseDetails.priority)) {
    errors.impact = 'If an issue blocks a critical customer operation, priority must be P0 or P1';
  }

  return errors;
}

/**
 * Returns a text paragraph with red text indicating a form field validation error.
 * 
 * @param {string} errorMessage A description of input value error.
 * @return {!TextParagraph} The resulting text paragraph.
 */
function createErrorTextParagraph(errorMessage) {
  return {
    textParagraph: {
      text: '<font color=\"#BA0300\"><b>Error:</b> ' + errorMessage + '</font>'
    }
  }
}


/**
 * Returns a submit form response that inserts a link into the document.
 * 
 * @param {string} title The title of the link to insert.
 * @param {string} url The URL of the link to insert.
 * @return {!SubmitFormResponse} The resulting submit form response.
 */
function createLinkRenderAction(title, url) {
  return {
    renderActions: {
      action: {
        links: [{
          title: title,
          url: url
        }]
      }
    }
  };
}

Python

python/3p-resources/create_3p_resources/main.py
# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License")
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https:#www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

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

import os
import flask
import functions_framework


@functions_framework.http
def create_3p_resources(req: flask.Request):
    """Responds to any HTTP request related to 3P resource creations.
    Args:
      req: An HTTP request context.
    Returns:
      An HTTP response context.
    """
    event = req.get_json(silent=True)
    parameters = event["commonEventObject"]["parameters"] if "parameters" in event["commonEventObject"] else None
    if parameters is not None and parameters["submitCaseCreationForm"]:
        return submit_case_creation_form(event)
    else:
        return create_case_input_card(event)




def create_case_input_card(event, errors = {}, isUpdate = False):
    """Produces a support case creation form card.
    Args:
      event: The event object.
      errors: An optional dict of per-field error messages.
      isUpdate: Whether to return the form as an update card navigation.
    Returns:
      The resulting card or action response.
    """
    card_header1 = {
        "title": "Create a support case"
    }

    card_section1_text_input1 = {
        "textInput": {
            "name": "name",
            "label": "Name"
        }
    }

    card_section1_text_input2 = {
        "textInput": {
            "name": "description",
            "label": "Description",
            "type": "MULTIPLE_LINE"
        }
    }

    card_section1_selection_input1 = {
        "selectionInput": {
            "name": "priority",
            "label": "Priority",
            "type": "DROPDOWN",
            "items": [{
                "text": "P0",
                "value": "P0"
            }, {
                "text": "P1",
                "value": "P1"
            }, {
                "text": "P2",
                "value": "P2"
            }, {
                "text": "P3",
                "value": "P3"
            }]
        }
    }

    card_section1_selection_input2 = {
        "selectionInput": {
            "name": "impact",
            "label": "Impact",
            "items": [{
                "text": "Blocks a critical customer operation",
                "value": "Blocks a critical customer operation"
            }]
        }
    }

    card_section1_button_list1_button1_action1 = {
        "function": os.environ["URL"],
        "parameters": [
        {
            "key": "submitCaseCreationForm",
            "value": True
        }
        ],
        "persistValues": True
    }

    card_section1_button_list1_button1 = {
        "text": "Create",
        "onClick": {
            "action": card_section1_button_list1_button1_action1
        }
    }

    card_section1_button_list1 = {
        "buttonList": {
            "buttons": [card_section1_button_list1_button1]
        }
    }

    # Builds the creation form and adds error text for invalid inputs.
    card_section1 = []
    if "name" in errors:
        card_section1.append(create_error_text_paragraph(errors["name"]))
    card_section1.append(card_section1_text_input1)
    if "description" in errors:
        card_section1.append(create_error_text_paragraph(errors["description"]))
    card_section1.append(card_section1_text_input2)
    if "priority" in errors:
        card_section1.append(create_error_text_paragraph(errors["priority"]))
    card_section1.append(card_section1_selection_input1)
    if "impact" in errors:
        card_section1.append(create_error_text_paragraph(errors["impact"]))

    card_section1.append(card_section1_selection_input2)
    card_section1.append(card_section1_button_list1)

    card = {
        "header": card_header1,
        "sections": [{
            "widgets": card_section1
        }]
    }

    if isUpdate:
        return {
            "renderActions": {
                "action": {
                        "navigations": [{
                        "updateCard": card
                    }]
                }
            }
        }
    else:
        return {
            "action": {
                "navigations": [{
                    "pushCard": card
                }]
            }
        }




def submit_case_creation_form(event):
    """Submits the creation form.

    If valid, returns a render action that inserts a new link
    into the document. If invalid, returns an update card navigation that
    re-renders the creation form with error messages.
    Args:
      event: The event object with form input values.
    Returns:
      The resulting response.
    """
    formInputs = event["commonEventObject"]["formInputs"] if "formInputs" in event["commonEventObject"] else None
    case_details = {
        "name":  None,
        "description": None,
        "priority": None,
        "impact": None,
    }
    if formInputs is not None:
        case_details["name"] = formInputs["name"]["stringInputs"]["value"][0] if "name" in formInputs else None
        case_details["description"] = formInputs["description"]["stringInputs"]["value"][0] if "description" in formInputs else None
        case_details["priority"] = formInputs["priority"]["stringInputs"]["value"][0] if "priority" in formInputs else None
        case_details["impact"] = formInputs["impact"]["stringInputs"]["value"][0] if "impact" in formInputs else False

    errors = validate_form_inputs(case_details)
    if len(errors) > 0:
        return create_case_input_card(event, errors, True) # Update mode
    else:
        title = f'Case {case_details["name"]}'
        # Adds the case details as parameters to the generated link URL.
        url = "https://example.com/support/cases/?" + urlencode(case_details)
        return create_link_render_action(title, url)




def validate_form_inputs(case_details):
    """Validates case creation form input values.
    Args:
      case_details: The values of each form input submitted by the user.
    Returns:
      A dict from field name to error message. An empty object represents a valid form submission.
    """
    errors = {}
    if case_details["name"] is None:
        errors["name"] = "You must provide a name"
    if case_details["description"] is None:
        errors["description"] = "You must provide a description"
    if case_details["priority"] is None:
        errors["priority"] = "You must provide a priority"
    if case_details["impact"] is not None and case_details["priority"] not in ['P0', 'P1']:
        errors["impact"] = "If an issue blocks a critical customer operation, priority must be P0 or P1"
    return errors


def create_error_text_paragraph(error_message):
    """Returns a text paragraph with red text indicating a form field validation error.
    Args:
      error_essage: A description of input value error.
    Returns:
      The resulting text paragraph.
    """
    return {
        "textParagraph": {
            "text": '<font color=\"#BA0300\"><b>Error:</b> ' + error_message + '</font>'
        }
    }




def create_link_render_action(title, url):
    """Returns a submit form response that inserts a link into the document.
    Args:
      title: The title of the link to insert.
      url: The URL of the link to insert.
    Returns:
      The resulting submit form response.
    """
    return {
        "renderActions": {
            "action": {
                "links": [{
                    "title": title,
                    "url": url
                }]
            }
        }
    }

다음 코드는 생성된 리소스의 링크 미리보기를 구현하는 방법을 보여줍니다.

python/3p-resources/create_link_preview/main.py
# Copyright 2023 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License")
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https:#www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

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/3p-resources/src/main/java/Create3pResources.java
/**
 * Copyright 2024 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

import org.apache.http.client.utils.URIBuilder;

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;

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

  /**
   * Responds to any HTTP request related to 3p resource creations.
   *
   * @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);
    JsonObject parameters = event.getAsJsonObject("commonEventObject").getAsJsonObject("parameters");
    if (parameters != null && parameters.has("submitCaseCreationForm") && parameters.get("submitCaseCreationForm").getAsBoolean()) {
      response.getWriter().write(gson.toJson(submitCaseCreationForm(event)));
    } else {
      response.getWriter().write(gson.toJson(createCaseInputCard(event, new HashMap<String, String>(), false)));
    }
  }


  /**
   * Produces a support case creation form.
   * 
   * @param event The event object.
   * @param errors A map of per-field error messages.
   * @param isUpdate Whether to return the form as an update card navigation.
   * @return The resulting card or action response.
   */
  JsonObject createCaseInputCard(JsonObject event, Map<String, String> errors, boolean isUpdate) {
    JsonObject cardHeader = new JsonObject();
    cardHeader.add("title", new JsonPrimitive("Create a support case"));

    JsonObject cardSectionTextInput1 = new JsonObject();
    cardSectionTextInput1.add("name", new JsonPrimitive("name"));
    cardSectionTextInput1.add("label", new JsonPrimitive("Name"));

    JsonObject cardSectionTextInput1Widget = new JsonObject();
    cardSectionTextInput1Widget.add("textInput", cardSectionTextInput1);

    JsonObject cardSectionTextInput2 = new JsonObject();
    cardSectionTextInput2.add("name", new JsonPrimitive("description"));
    cardSectionTextInput2.add("label", new JsonPrimitive("Description"));
    cardSectionTextInput2.add("type", new JsonPrimitive("MULTIPLE_LINE"));

    JsonObject cardSectionTextInput2Widget = new JsonObject();
    cardSectionTextInput2Widget.add("textInput", cardSectionTextInput2);

    JsonObject cardSectionSelectionInput1ItemsItem1 = new JsonObject();
    cardSectionSelectionInput1ItemsItem1.add("text", new JsonPrimitive("P0"));
    cardSectionSelectionInput1ItemsItem1.add("value", new JsonPrimitive("P0"));

    JsonObject cardSectionSelectionInput1ItemsItem2 = new JsonObject();
    cardSectionSelectionInput1ItemsItem2.add("text", new JsonPrimitive("P1"));
    cardSectionSelectionInput1ItemsItem2.add("value", new JsonPrimitive("P1"));

    JsonObject cardSectionSelectionInput1ItemsItem3 = new JsonObject();
    cardSectionSelectionInput1ItemsItem3.add("text", new JsonPrimitive("P2"));
    cardSectionSelectionInput1ItemsItem3.add("value", new JsonPrimitive("P2"));

    JsonObject cardSectionSelectionInput1ItemsItem4 = new JsonObject();
    cardSectionSelectionInput1ItemsItem4.add("text", new JsonPrimitive("P3"));
    cardSectionSelectionInput1ItemsItem4.add("value", new JsonPrimitive("P3"));

    JsonArray cardSectionSelectionInput1Items = new JsonArray();
    cardSectionSelectionInput1Items.add(cardSectionSelectionInput1ItemsItem1);
    cardSectionSelectionInput1Items.add(cardSectionSelectionInput1ItemsItem2);
    cardSectionSelectionInput1Items.add(cardSectionSelectionInput1ItemsItem3);
    cardSectionSelectionInput1Items.add(cardSectionSelectionInput1ItemsItem4);

    JsonObject cardSectionSelectionInput1 = new JsonObject();
    cardSectionSelectionInput1.add("name", new JsonPrimitive("priority"));
    cardSectionSelectionInput1.add("label", new JsonPrimitive("Priority"));
    cardSectionSelectionInput1.add("type", new JsonPrimitive("DROPDOWN"));
    cardSectionSelectionInput1.add("items", cardSectionSelectionInput1Items);

    JsonObject cardSectionSelectionInput1Widget = new JsonObject();
    cardSectionSelectionInput1Widget.add("selectionInput", cardSectionSelectionInput1);

    JsonObject cardSectionSelectionInput2ItemsItem = new JsonObject();
    cardSectionSelectionInput2ItemsItem.add("text", new JsonPrimitive("Blocks a critical customer operation"));
    cardSectionSelectionInput2ItemsItem.add("value", new JsonPrimitive("Blocks a critical customer operation"));

    JsonArray cardSectionSelectionInput2Items = new JsonArray();
    cardSectionSelectionInput2Items.add(cardSectionSelectionInput2ItemsItem);

    JsonObject cardSectionSelectionInput2 = new JsonObject();
    cardSectionSelectionInput2.add("name", new JsonPrimitive("impact"));
    cardSectionSelectionInput2.add("label", new JsonPrimitive("Impact"));
    cardSectionSelectionInput2.add("items", cardSectionSelectionInput2Items);

    JsonObject cardSectionSelectionInput2Widget = new JsonObject();
    cardSectionSelectionInput2Widget.add("selectionInput", cardSectionSelectionInput2);

    JsonObject cardSectionButtonListButtonActionParametersParameter = new JsonObject();
    cardSectionButtonListButtonActionParametersParameter.add("key", new JsonPrimitive("submitCaseCreationForm"));
    cardSectionButtonListButtonActionParametersParameter.add("value", new JsonPrimitive(true));

    JsonArray cardSectionButtonListButtonActionParameters = new JsonArray();
    cardSectionButtonListButtonActionParameters.add(cardSectionButtonListButtonActionParametersParameter);

    JsonObject cardSectionButtonListButtonAction = new JsonObject();
    cardSectionButtonListButtonAction.add("function", new JsonPrimitive(System.getenv().get("URL")));
    cardSectionButtonListButtonAction.add("parameters", cardSectionButtonListButtonActionParameters);
    cardSectionButtonListButtonAction.add("persistValues", new JsonPrimitive(true));

    JsonObject cardSectionButtonListButtonOnCLick = new JsonObject();
    cardSectionButtonListButtonOnCLick.add("action", cardSectionButtonListButtonAction);

    JsonObject cardSectionButtonListButton = new JsonObject();
    cardSectionButtonListButton.add("text", new JsonPrimitive("Create"));
    cardSectionButtonListButton.add("onClick", cardSectionButtonListButtonOnCLick);

    JsonArray cardSectionButtonListButtons = new JsonArray();
    cardSectionButtonListButtons.add(cardSectionButtonListButton);

    JsonObject cardSectionButtonList = new JsonObject();
    cardSectionButtonList.add("buttons", cardSectionButtonListButtons);

    JsonObject cardSectionButtonListWidget = new JsonObject();
    cardSectionButtonListWidget.add("buttonList", cardSectionButtonList);

    // Builds the form inputs with error texts for invalid values.
    JsonArray cardSection = new JsonArray();
    if (errors.containsKey("name")) {
      cardSection.add(createErrorTextParagraph(errors.get("name").toString()));
    }
    cardSection.add(cardSectionTextInput1Widget);
    if (errors.containsKey("description")) {
      cardSection.add(createErrorTextParagraph(errors.get("description").toString()));
    }
    cardSection.add(cardSectionTextInput2Widget);
    if (errors.containsKey("priority")) {
      cardSection.add(createErrorTextParagraph(errors.get("priority").toString()));
    }
    cardSection.add(cardSectionSelectionInput1Widget);
    if (errors.containsKey("impact")) {
      cardSection.add(createErrorTextParagraph(errors.get("impact").toString()));
    }

    cardSection.add(cardSectionSelectionInput2Widget);
    cardSection.add(cardSectionButtonListWidget);

    JsonObject cardSectionWidgets = new JsonObject();
    cardSectionWidgets.add("widgets", cardSection);

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

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

    JsonObject navigation = new JsonObject();
    if (isUpdate) {
      navigation.add("updateCard", card);
    } else {
      navigation.add("pushCard", card);
    }

    JsonArray navigations = new JsonArray();
    navigations.add(navigation);

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

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

    if (!isUpdate) {
      return renderActions;
    }

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

    return update;
  }


  /**
   * Submits the creation form. If valid, returns a render action
   * that inserts a new link into the document. If invalid, returns an
   * update card navigation that re-renders the creation form with error messages.
   * 
   * @param event The event object with form input values.
   * @return The resulting response.
   */
  JsonObject submitCaseCreationForm(JsonObject event) throws Exception {
    JsonObject formInputs = event.getAsJsonObject("commonEventObject").getAsJsonObject("formInputs");
    Map<String, String> caseDetails = new HashMap<String, String>();
    if (formInputs != null) {
      if (formInputs.has("name")) {
        caseDetails.put("name", formInputs.getAsJsonObject("name").getAsJsonObject("stringInputs").getAsJsonArray("value").get(0).getAsString());
      }
      if (formInputs.has("description")) {
        caseDetails.put("description", formInputs.getAsJsonObject("description").getAsJsonObject("stringInputs").getAsJsonArray("value").get(0).getAsString());
      }
      if (formInputs.has("priority")) {
        caseDetails.put("priority", formInputs.getAsJsonObject("priority").getAsJsonObject("stringInputs").getAsJsonArray("value").get(0).getAsString());
      }
      if (formInputs.has("impact")) {
        caseDetails.put("impact", formInputs.getAsJsonObject("impact").getAsJsonObject("stringInputs").getAsJsonArray("value").get(0).getAsString());
      }
    }

    Map<String, String> errors = validateFormInputs(caseDetails);
    if (errors.size() > 0) {
      return createCaseInputCard(event, errors, /* isUpdate= */ true);
    } else {
      String title = String.format("Case %s", caseDetails.get("name"));
      // Adds the case details as parameters to the generated link URL.
      URIBuilder uriBuilder = new URIBuilder("https://example.com/support/cases/");
      for (String caseDetailKey : caseDetails.keySet()) {
        uriBuilder.addParameter(caseDetailKey, caseDetails.get(caseDetailKey));
      }
      return createLinkRenderAction(title, uriBuilder.build().toURL().toString());
    }
  }


  /**
   * Validates case creation form input values.
   * 
   * @param caseDetails The values of each form input submitted by the user.
   * @return A map from field name to error message. An empty object
   *     represents a valid form submission.
   */
  Map<String, String> validateFormInputs(Map<String, String> caseDetails) {
    Map<String, String> errors = new HashMap<String, String>();
    if (!caseDetails.containsKey("name")) {
      errors.put("name", "You must provide a name");
    }
    if (!caseDetails.containsKey("description")) {
      errors.put("description", "You must provide a description");
    }
    if (!caseDetails.containsKey("priority")) {
      errors.put("priority", "You must provide a priority");
    }
    if (caseDetails.containsKey("impact") && !Arrays.asList(new String[]{"P0", "P1"}).contains(caseDetails.get("priority"))) {
      errors.put("impact", "If an issue blocks a critical customer operation, priority must be P0 or P1");
    }

    return errors;
  }

  /**
   * Returns a text paragraph with red text indicating a form field validation error.
   * 
   * @param errorMessage A description of input value error.
   * @return The resulting text paragraph.
   */
  JsonObject createErrorTextParagraph(String errorMessage) {
    JsonObject textParagraph = new JsonObject();
    textParagraph.add("text", new JsonPrimitive("<font color=\"#BA0300\"><b>Error:</b> " + errorMessage + "</font>"));

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

    return textParagraphWidget;
  }


  /**
   * Returns a submit form response that inserts a link into the document.
   * 
   * @param title The title of the link to insert.
   * @param url The URL of the link to insert.
   * @return The resulting submit form response.
   */
  JsonObject createLinkRenderAction(String title, String url) {
    JsonObject link = new JsonObject();
    link.add("title", new JsonPrimitive(title));
    link.add("url", new JsonPrimitive(url));

    JsonArray links = new JsonArray();
    links.add(link);

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

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

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

    return linkRenderAction;
  }

}

다음 코드는 생성된 리소스의 링크 미리보기를 구현하는 방법을 보여줍니다.

java/3p-resources/src/main/java/CreateLinkPreview.java
/**
 * Copyright 2024 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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

}