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

Bu kılavuzda, kullanıcıların Google Workspace Flows'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 Akışları'na özel işlevler ve özellikler içerir.

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": "Sample add-on",
      "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": "onExecuteCalculate"
          }
        }
      ]
    }
  }
}

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() {
  var card = {
    "sections": [
      {
        "header": "Choose a Chat space",
        "widgets": [
          {
            "selectionInput": {
              "name": "value1",
              "label": "First value",
              "type": "MULTI_SELECT",
              "platformDataSource": {
                "hostAppDataSource": {
                  "workflowDataSource": {
                    "includeVariables": true,
                    "type": "SPACE"
                  }
                }
              }
            }
          }
        ]
      }
    ]
  };
  return {
    "action": {
      "navigations": [{
        "push_card": card
      }]
    }
  };
}

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 100'e kadar ö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
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

// 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 ...
}

Google Workspace verilerini otomatik tamamlama

Ayrıca, kullanıcının Google Workspace ortamındaki verilerden otomatik tamamlama önerileri de doldurabilirsiniz:

  • Google Workspace kullanıcıları: Aynı Google Workspace kuruluşundaki kullanıcıları doldurun.
  • Google Chat alanları: Kullanıcının üyesi olduğu Google Chat alanlarını doldurur.

Bunu yapılandırmak için PlatformDataSource öğesini SelectionInput widget'ında ayarlayın ve WorkflowDataSourceType öğesini USER veya SPACE olarak belirtin.

Apps Komut Dosyası

// User Autocomplete
var multiSelect2 =
  CardService.newSelectionInput()
    .setFieldName("value2")
    .setTitle("User Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.USER)
            ))
    );

// Chat Space Autocomplete
var multiSelect3 =
  CardService.newSelectionInput()
    .setFieldName("value3")
    .setTitle("Chat Space Autocomplete")
    .setType(CardService.SelectionInputType.MULTI_SELECT)
    .setMultiSelectMaxSelectedItems(3)
    .setPlatformDataSource(
      CardService.newPlatformDataSource()
        .setHostAppDataSource(
          CardService.newHostAppDataSource()
            .setWorkflowDataSource(
              CardService.newWorkflowDataSource()
                .setIncludeVariables(true)
                .setType(CardService.WorkflowDataSourceType.SPACE)
            ))
    );

Örnek: Otomatik tamamlama türlerini birleştirme

Aşağıdaki örnekte, sunucu tarafı, kullanıcı ve alan otomatik tamamlama özelliğini gösteren üç SelectionInput widget'ı içeren bir kart oluşturan onConfig işlevi gösterilmektedir:

Apps Komut Dosyası

function onConfigAutocompleteTest(event) {
  // Handle autocomplete request
  if (event.workflow && event.workflow.elementUiAutocomplete) {
    return handleAutocompleteRequest(event);
  }

  // Server-side autocomplete widget
  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)
                  ))
          )
      );

  // User autocomplete widget
  var multiSelect2 =
    CardService.newSelectionInput()
      .setFieldName("value2")
      .setTitle("User Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.USER)
              ))
      );

  // Space autocomplete widget
  var multiSelect3 =
    CardService.newSelectionInput()
      .setFieldName("value3")
      .setTitle("Chat Space Autocomplete")
      .setType(CardService.SelectionInputType.MULTI_SELECT)
      .setMultiSelectMaxSelectedItems(3)
      .setPlatformDataSource(
        CardService.newPlatformDataSource()
          .setHostAppDataSource(
            CardService.newHostAppDataSource()
              .setWorkflowDataSource(
                CardService.newWorkflowDataSource()
                  .setIncludeVariables(true)
                  .setType(CardService.WorkflowDataSourceType.SPACE)
              ))
      );

  var sectionBuilder =
    CardService.newCardSection()
      .addWidget(multiSelect1)
      .addWidget(multiSelect2)
      .addWidget(multiSelect3);

  var card =
    CardService.newCardBuilder()
      .addSection(sectionBuilder)
      .build();
  return card;
}

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
  var autocompleteResponse = [
    {
      "text": query + " option 1",
      "value": query + "_option1",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    },
    {
      "text": query + " option 2",
      "value": query + "_option2",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png",
      "bottom_text": "subtitle of option 2"
    },
    {
      "text": query + " option 3",
      "value": query + "_option3",
      "start_icon_uri": "https://developers.google.com/workspace/add-ons/images/person-icon.png"
    }
  ];

  var response = {
    "action": {
      "modify_operations": [
        {
          "update_widget": {
            "selection_input_widget_suggestions": {
              "suggestions": autocompleteResponse
            }
          }
        }
      ]
    }
  };
  return response;
}

Workspace Flows'a özel özellikler

Bazı kart widget'ları, Workspace Akışları'na özel işlevler ve özellikler içerir. Bu işlevler ve özellikler hakkında ayrıntılı bilgiyi burada bulabilirsiniz.

TextInput ve SelectionInput

TextInput ve SelectionInput widget'ları, Workspace Akışları'na özel şu özelliklere sahiptir:

  • includeVariables: Kullanıcıların önceki adımlardaki değişkenleri seçmesine olanak tanıyan bir Boole özelliği.
  • type: Önerileri otomatik tamamlayan numaralandırılmış bir değer. Desteklenen değerler:
    • USER: Kullanıcının kişilerinde bulunan kişiler için otomatik tamamlama önerileri sağlar.
    • SPACE: Kullanıcının üyesi olduğu Google Chat alanları için otomatik tamamlama önerileri sunar.

Hem includeVariables hem de type ayarlandığında giriş alanı, deneyimlerini birleştirir. Kullanıcılar, açılır menüden eşleşen type değişkenini seçebilir ve bu değişkenle ilgili otomatik tamamlama önerilerini görebilir.

  • Google Chat alanı için otomatik tamamlama önerileri.
    Şekil 1: Bir kullanıcı, alan seçerken otomatik tamamlama önerilerini inceliyor.
  • Değişkenler menüsü, kullanıcıların önceki adımlardan çıkış değişkenleri seçmesine olanak tanır.
    Şekil 2: Bir kullanıcı, önceki adımın çıkış değişkenini ➕Değişkenler açılır listesinden seçiyor.

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

  • Kart navigasyonu (ör. popCard(), pushCard() ve updateCard()) akışları genişleten eklentilerde desteklenmez.

  • SelectionInput değişken seçicide kullanıldığında widget'lar yalnızca "type": "MULTI_SELECT" değerini destekler. Yapılandırma kartlarının diğer bölümlerinde SelectionInput, SelectionType değerlerinin tümünü destekler.