Bir adım için yapılandırma kartı oluşturma

Bu kılavuzda, kullanıcıların Google Workspace Studio'daki bir adımı özelleştirmesine ve bu adıma giriş sağlamasına olanak tanıyan bir yapılandırma kartının nasıl oluşturulacağı açıklanmaktadır.

Genel olarak, yapılandırma kartı oluşturmak için diğer Google Workspace eklentilerinde olduğu gibi bir kart arayüzü oluşturursunuz. Yapılandırma kartı arayüzleri oluşturma konusunda yardım almak için aşağıdaki kaynaklara bakın:

  • Kart oluşturmanıza ve tanımlamanıza yardımcı olan etkileşimli bir araç olan Kart Oluşturucu.
  • Google Workspace Eklentileri API referans belgelerindeki Card.
  • Card Service, komut dosyalarının kartları yapılandırmasına ve oluşturmasına olanak tanıyan bir Apps Komut Dosyası hizmetidir.
  • Google Workspace eklentileri geliştirici belgelerindeki kart tabanlı arayüzler.

Bazı kart widget'ları, bu kılavuzda ayrıntılı olarak açıklanan Workspace Studio'ya özel işlevlere ve özelliklere sahiptir.

Yapılandırma kartı tanımlama

Hem Apps Komut Dosyası manifestinde hem de kodda bir yapılandırma kartı tanımlayın.

Aşağıdaki örnekte, kullanıcılardan Google Chat alanı seçmelerini isteyen bir yapılandırma kartının nasıl oluşturulacağı gösterilmektedir.

Manifest dosyasını düzenleme

Manifest dosyasında workflowElements öğesini tanımlayın.

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Chat space selector",
      "logoUrl": "https://www.gstatic.com/images/branding/productlogos/gsuite_addons/v6/web-24dp/logo_gsuite_addons_color_1x_web_24dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "actionElement",
          "state": "ACTIVE",
          "name": "Chat space selector",
          "description": "Lets the user select a space from Google  Chat",
          "workflowAction": {
            "inputs": [
              {
                "id": "chooseSpace",
                "description": "Choose a Chat space",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfigSpacePicker",
            "onExecuteFunction": "onExecuteSpacePicker"
          }
        }
      ]
    }
  }
}

Kodu düzenle

Uygulama kodunda bir kart döndürün.

Apps Komut Dosyası

/**
 * Generates and displays a configuration card to choose a Chat space
 */
function onConfigSpacePicker() {

  const selectionInput = CardService.newSelectionInput()
    .setTitle("First Value")
    .setFieldName("chooseSpace")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            )
        )
    );

  const cardSection = CardService.newCardSection()
    .setHeader("Select Chat Space")
    .setId("section_1")
    .addWidget(selectionInput)

  var card = CardService.newCardBuilder()
    .addSection(cardSection)
    .build();

  return card;
}

function onExecuteSpacePicker(e) {
}

Giriş widget'ları için otomatik tamamlama özelliğini ayarlama

Kullanıcıların seçenek listesinden seçim yapmasına yardımcı olmak için SelectionInput widget'larında otomatik tamamlamayı yapılandırabilirsiniz. Örneğin, bir kullanıcı ABD'deki şehirleri dolduran bir menü için Atl yazmaya başlarsa kullanıcı yazmayı bitirmeden önce öğeniz Atlanta için otomatik öneride bulunabilir. En fazla 100 öğeyi otomatik olarak tamamlayabilirsiniz.

Otomatik tamamlama önerileri aşağıdaki veri kaynaklarından gelebilir:

  • Sunucu tarafı otomatik tamamlama: Öneriler, tanımladığınız üçüncü taraf veya harici bir veri kaynağından doldurulur.
  • Google Workspace verileri: Öneriler, Google Workspace kullanıcıları veya Google Chat alanları gibi Google Workspace kaynaklarından alınır.

Sunucu tarafı otomatik tamamlama

Harici bir veri kaynağındaki önerileri otomatik olarak tamamlayacak şekilde bir SelectionInput widget'ı yapılandırabilirsiniz. Örneğin, kullanıcıların bir müşteri ilişkileri yönetimi (CRM) sistemindeki satış potansiyel müşterileri listesinden seçim yapmasına yardımcı olabilirsiniz.

Sunucu taraflı otomatik tamamlama özelliğini uygulamak için:

  1. Veri kaynağını tanımlayın: SelectionInput widget'ında RemoteDataSource belirten bir DataSourceConfig ekleyin. Bu yapılandırma, otomatik tamamlama önerilerini getiren bir Apps Komut Dosyası işlevini gösterir.
  2. Otomatik tamamlama işlevini uygulayın: Bu işlev, kullanıcı giriş alanına yazdığında tetiklenir. İşlev, kullanıcının girişine göre harici veri kaynağınızı sorgulamalı ve bir öneri listesi döndürmelidir.

Aşağıdaki örnekte, sunucu tarafında otomatik tamamlama için bir SelectionInput widget'ının nasıl yapılandırılacağı gösterilmektedir:

Apps Komut Dosyası

// In your onConfig function:
var multiSelect1 =
  CardService.newSelectionInput()
    .setFieldName("value1")
    .setTitle("Server Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setRemoteDataSource(
          CardService.newAction().setFunctionName('getAutocompleteResults')
        )
    )
    .addDataSourceConfig(
      CardService.newDataSourceConfig()
        .setPlatformDataSource(
          CardService.newPlatformDataSource()
            .setHostAppDataSource(
              CardService.newHostAppDataSource()
                .setWorkflowDataSource(
                  CardService.newWorkflowDataSource()
                    .setIncludeVariables(true)
                ))
        )
    );

// ... add widget to card ...

Otomatik tamamlama isteğini işleme

setFunctionName içinde belirtilen işlev (ör. getAutocompleteResults) Kullanıcı alana yazdığında bir etkinlik nesnesi alır. Bu işlev:

  1. event.workflow.elementUiAutocomplete.invokedFunction öğesinin beklenen işlev adıyla eşleştiğinden emin olmak için öğeyi kontrol edin.
  2. Kullanıcının event.workflow.elementUiAutocomplete.query girişini alın.
  3. Sorguyu kullanarak harici veri kaynağını sorgulayın.
  4. Gerekli biçimde en fazla 100 öneri döndürür.

Aşağıdaki örnekte, kullanıcının sorgusuna göre öneri döndürmek için handleAutocompleteRequest() işlevinin nasıl uygulanacağı gösterilmektedir:

Apps Komut Dosyası

function handleAutocompleteRequest(event) {
  var invokedFunction = event.workflow.elementUiAutocomplete.invokedFunction;
  var query = event.workflow.elementUiAutocomplete.query;

  if (invokedFunction != "getAutocompleteResults" || query == undefined || query == "") {
    return {};
  }

  // Query your data source to get results based on the query
  let autocompleteResponse = AddOnsResponseService.newUpdateWidget()
    .addSuggestion(
      query + " option 1",
      query + "_option1",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 1 bottom text"
    )
    .addSuggestion(
      query + " option 2",
      query + "_option2",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 2 bottom text"
    ).addSuggestion(
      query + " option 3",
      query + "_option3",
      false,
      "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "option 3 bottom text"
    );

  const modifyAction = AddOnsResponseService.newAction()
    .addModifyCard(
      AddOnsResponseService.newModifyCard()
        .setUpdateWidget(autocompleteResponse)
    );

  return AddOnsResponseService.newRenderActionBuilder()
    .setAction(modifyAction)
    .build();
}

// In your onConfig function, handle the autocomplete event
function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // ... rest of your card building logic ...
}

Kartla ilgili dikkat edilmesi gereken noktalar ve sınırlamalar