Bu kılavuzda, giriş değişkeninin nasıl oluşturulacağı açıklanmaktadır.
Adımların çalışması için belirli bilgiler gerekir. Örneğin, e-posta göndermek için e-posta adresi gerekir. Bu gerekli bilgileri sağlamak için giriş değişkenlerini tanımlayın. Tanımlandıktan sonra giriş değişkenleri genellikle kullanıcı tarafından adımın yapılandırma kartında, adım ayarlanırken belirlenir.
Giriş değişkenini iki yerde tanımlayın: eklentinin manifest dosyasında ve kullanıcıların giriş değişkenleri için değer girebileceği bir yapılandırma kartıyla birlikte kodda.
Giriş değişkenini manifest dosyasında tanımlayın
Manifest dosyasında, giriş değişkenlerini inputs[] dizisiyle belirtin. inputs[] dizisindeki her öğe şu özelliklere sahiptir:
id: Giriş değişkeninin benzersiz tanımlayıcısı. Akışın bir yapılandırma kartı giriş öğesini bu giriş değişkeniyle ilişkilendirmesine izin vermek için, öğenin adı karşılık gelen kart öğesinin adıyla eşleşmelidir.description: Son kullanıcılara gösterilecek giriş değişkeninin açıklaması.cardinality: Kaç değere izin verilir? Olası değerler:SINGLE: Yalnızca bir değere izin verilir.
dataType: Kabul edilen değer türü.dataType, veri türünü tanımlayanbasicTypeözelliğine sahiptir. Geçerli değerler şunlardır:STRING: Alfanümerik bir dize.INTEGER: Bir sayı.TIMESTAMP: "Unix sıfır zamanından itibaren milisaniye" biçimindeki zaman damgası. Örneğin, 27 Kasım 2025, 16:49:02 UTC değeri1764262142988olarak gösterilir.BOOLEAN: Doğru veya yanlış.EMAIL_ADDRESS:dana@example.combiçiminde bir e-posta adresi.
Aşağıdaki örnekte, bir hesap makinesi adımı için üç giriş değişkeni tanımlanmaktadır. İlk iki giriş değişkeni tam sayı, üçüncü değişken ise aritmetik işlemdir.
JSON
{
"timeZone": "America/Los_Angeles",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Calculator",
"logoUrl": "https://www.gstatic.com/images/branding/productlogos/calculator_search/v1/web-24dp/logo_calculator_search_color_1x_web_24dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "calculatorDemo",
"state": "ACTIVE",
"name": "Calculate",
"description": "Asks the user for two values and a math operation, then performs the math operation on the values and outputs the result.",
"workflowAction": {
"inputs": [
{
"id": "value1",
"description": "value1",
"cardinality": "SINGLE",
"dataType": {
"basicType": "INTEGER"
}
},
{
"id": "value2",
"description": "value2",
"cardinality": "SINGLE",
"dataType": {
"basicType": "INTEGER"
}
},
{
"id": "operation",
"description": "operation",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"outputs": [
{
"id": "result",
"description": "Calculated result",
"cardinality": "SINGLE",
"dataType": {
"basicType": "INTEGER"
}
}
],
"onConfigFunction": "onConfigCalculate",
"onExecuteFunction": "onExecuteCalculate"
}
}
]
}
}
}
Giriş değişkenini kodda tanımlama
Adımın kodunda, manifest dosyasının inputs[] dizisinde tanımlanan her giriş değişkeni için bir giriş kartı widget'ı tanımlayan bir yapılandırma kartı döndüren onConfigFunction() adlı bir işlev bulunur.
Yapılandırma kartında tanımlanan giriş widget'ları aşağıdaki koşulları karşılamalıdır:
- Her giriş widget'ının
name, manifest dosyasındaki ilgili giriş değişkenininidile eşleşmelidir. - Giriş widget'ının kardinalitesi, manifest dosyasındaki giriş değişkeninin
cardinalityile eşleşmelidir. - Giriş widget'ının veri türü, giriş değişkeninin
dataTypeile eşleşmelidir. Giriş değişkeninindataTypedeğeri tamsayı ise dize tutamaz.
Kart arayüzleri oluşturma konusunda yardım almak için aşağıdaki seçeneklerden birine bakın:
- Kart Oluşturucu: Kart oluşturmak ve tanımlamak için kullanabileceğiniz etkileşimli bir araçtır.
- Card: Google Workspace eklenti API'si referans belgelerinde.
- Card Service: Komut dosyalarının kartları yapılandırmasına ve oluşturmasına olanak tanıyan bir Apps Script hizmetidir.
- Kart tabanlı arayüzlere genel bakış: Google Workspace eklenti geliştirici dokümanlarında.
Aşağıdaki örnekte, Define the input variable in the manifest file (Giriş değişkenini manifest dosyasında tanımlama) bölümünde tanımlanan her giriş widget'ı için bir yapılandırma kartı döndürülmektedir.
Apps Komut Dosyası
/**
* Generates and displays a configuration card for the sample calculation step.
*
* This function creates a card with input fields for two values and a drop-down
* for selecting an arithmetic operation.
*
* The input fields are configured to let the user select outputs from previous
* workflow steps as input values using the `hostAppDataSource` property.
*/
function onConfigCalculate() {
const firstInput = CardService.newTextInput()
.setFieldName("value1") // "FieldName" must match an "id" in the manifest file's inputs[] array.
.setTitle("First Value")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
);
const secondInput = CardService.newTextInput()
.setFieldName("value2") // "FieldName" must match an "id" in the manifest file's inputs[] array.
.setTitle("Second Value")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
);
const selectionInput = CardService.newSelectionInput()
.setTitle("operation")
.setFieldName("operation") // "FieldName" must match an "id" in the manifest file's inputs[] array.
.setType(CardService.SelectionInputType.DROPDOWN)
.addItem("+", "+", false)
.addItem("-", "-", true)
.addItem("x", "x", false)
.addItem("/", "/", false);
const sections = CardService.newCardSection()
.setHeader("Action_sample: Calculate")
.setId("section_1")
.addWidget(firstInput)
.addWidget(selectionInput)
.addWidget(secondInput)
let card = CardService.newCardBuilder()
.addSection(sections)
.build();
return card;
}
Önceki adımlardaki çıktı değişkenlerini kullanma
Giriş değişkenlerini, iş akışındaki önceki adımlardan gelen çıkış değişkenlerini kabul edecek şekilde yapılandırabilirsiniz.
Değişken seçimini etkinleştirme
Kullanıcıların önceki adımlardaki değişkenleri seçmesine izin vermek için includeVariables
özelliğini TextInput ve SelectionInput widget'larında kullanın.
TextInput ve SelectionInput widget'ları, Workspace Studio'ya özel şu özelliklere sahiptir:
includeVariables: Kullanıcıların önceki adımlardaki değişkenleri seçmesine olanak tanıyan bir Boole özelliği. Değişken seçicinin sonraki adımlarda gösterilmesi için hem başlangıç etkinliği hem de en az bir karşılık gelen çıkış değişkeni, değişkenle eşlenmelidir.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.
-
Şekil 4: Bir kullanıcı, alan seçerken otomatik tamamlama önerilerini inceliyor. -
Şekil 5: Bir kullanıcı, ➕Değişkenler açılır listesinden önceki bir adımın çıkış değişkenini seçiyor.
Taşma menüsüyle yalnızca bir çıkış değişkeni seçin
Kullanıcıların taşma menüsünü kullanarak önceki bir adımdan tek bir çıkış değişkeni seçmesine olanak tanımak için SelectionInput
widget'ını yapılandırabilirsiniz.
SelectionInputType seçeneğini OVERFLOW_MENU olarak ayarladığınızda widget, özel bir değişken seçici olarak kullanılır. Değişken değerlerini dizelere dönüştüren includeVariables ile TextInput kullanımının aksine, OVERFLOW_MENU seçilen değişkenin orijinal veri türünü korur.
Apps Komut Dosyası
const selectionInput = CardService.newSelectionInput()
.setFieldName("variable_picker_1")
.setTitle("Variable Picker")
.setType(
CardService.SelectionInputType.OVERFLOW_MENU
);
Kullanıcıların metin ve çıkış değişkenlerini birleştirmesine izin verme
Kullanıcıların TextInput
metin ve çıkış değişkenleriyle nasıl etkileşimde bulunacağını kontrol etmek için setInputMode() kullanarak widget'ları yapılandırabilirsiniz.
RICH_TEXT: Kullanıcıların metin ve çıkış değişkenlerini birleştirmesine olanak tanır. Sonuç, tek bir birleştirilmiş dizedir.PLAIN_TEXT: Girişi kısıtlar. Kullanıcılar metin yazabilir veya tek bir çıkış değişkeni seçebilir. Bir değişken seçtiğinizde mevcut metinler değiştirilir. Manifestte tanımlanan belirli veri türlerini zorunlu kılmak için bu modu kullanın.
Aşağıdaki resimde iki TextInput widget'ı gösterilmektedir. İlki RICH_TEXT olarak yapılandırılır ve metin ile bir çıkış değişkeni içerir. İkincisi PLAIN_TEXT olarak yapılandırılır ve yalnızca bir çıkış değişkenine izin verir.
-
Şekil 3: RICH_TEXTvePLAIN_TEXTolarak yapılandırılmış metin girişi widget'ları.
Tüm TextInput widget'ları için giriş modunu açıkça ayarlamanızı öneririz.
Farklı giriş modlarına sahip TextInput widget'larını yapılandırmak için manifest dosyasını aşağıda bulabilirsiniz:
JSON
{
"timeZone": "America/Toronto",
"dependencies": {},
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Text and output variable demo",
"logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "richTextDemo",
"state": "ACTIVE",
"name": "Rich Text Demo",
"description": "Show the difference between rich text and plain text TextInput widgets",
"workflowAction": {
"inputs": [
{
"id": "value1",
"description": "First user input",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
},
{
"id": "value2",
"description": "Second user input",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"onConfigFunction": "onConfiguration",
"onExecuteFunction": "onExecution"
}
}
]
}
}
}
Farklı giriş modlarına sahip TextInput widget'larını yapılandırmak için gereken kodu aşağıda bulabilirsiniz:
Apps Komut Dosyası
function onConfiguration() {
const input1 = CardService.newTextInput()
.setFieldName("value1")
.setId("value1")
.setTitle("Rich Text")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
)
// Set input mode to RICH_TEXT to allow mixed text and variables.
.setInputMode(CardService.TextInputMode.RICH_TEXT);
const input2 = CardService.newTextInput()
.setFieldName("value2")
.setId("value2")
.setTitle("Plain text")
.setHostAppDataSource(
CardService.newHostAppDataSource()
.setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
)
)
// Set input mode to PLAIN_TEXT to enforce single variable selection.
.setInputMode(CardService.TextInputMode.PLAIN_TEXT);
const section = CardService.newCardSection()
.addWidget(input1)
.addWidget(input2);
const card = CardService.newCardBuilder()
.addSection(section)
.build();
return card;
}
function onExecution(e) {
}
Değişken seçici düğmelerini özelleştirme
Düğme boyutunu ve etiketini ayarlayarak değişken seçici düğmesini özelleştirebilirsiniz.
Düğme boyutu
Düğme boyutunu ayarlamak için aşağıdaki VariableButtonSize enum'larından biriyle birlikte setVariableButtonSize() öğesini kullanın:
UNSPECIFIED: Varsayılan değer. Düğme, yan panelde kompakt, diğer bağlamlarda ise tam boyuttadır.COMPACT: Düğmede yalnızca artı işareti (+) gösterilir.FULL_SIZE: Düğmede tam metin etiketi gösterilir.
Düğme etiketi
Düğme metnini ayarlamak için setVariableButtonLabel() simgesini kullanın.
Örnek: Değişken seçici özelleştirme
Aşağıdaki örnekte, farklı değişken seçici düğme boyutlarına ve özel etikete sahip TextInput widget'larının nasıl yapılandırılacağı gösterilmektedir.
-
Şekil 1: Web'de değişken seçici düğmesinin özelleştirilmesi. -
Şekil 2: Eklenti yan panelinde değişken seçici düğmesi özelleştirme.
Değişken seçici düğmelerini özelleştirmeye yönelik manifest dosyası:
JSON
{
"timeZone": "America/Los_Angeles",
"dependencies": {},
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"oauthScopes": [
"https://www.googleapis.com/auth/script.locale"
],
"addOns": {
"common": {
"name": "Variable button customization",
"logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "variable_picker_customization",
"state": "ACTIVE",
"name": "Variable Picker demo",
"description": "List all possible variable picker customization options",
"workflowAction": {
"onConfigFunction": "onUpdateCardConfigFunction",
"onExecuteFunction": "onUpdateCardExecuteFunction"
}
}
]
}
}
}
Değişken seçici düğmelerini özelleştirmeye yönelik kod:
Apps Komut Dosyası
function onUpdateCardConfigFunction(event) {
const textInput1 = CardService.newTextInput()
.setFieldName("value1")
.setTitle("Regular variable picker button")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
)
);
const textInput2 = CardService.newTextInput()
.setFieldName("value2")
.setTitle("Size: Unspecified")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.UNSPECIFIED)
)
);
const textInput3 = CardService.newTextInput()
.setFieldName("value3")
.setTitle("Size: Full size")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.FULL_SIZE)
)
);
const textInput4 = CardService.newTextInput()
.setFieldName("value4")
.setTitle("Size: Compact")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonSize(CardService.VariableButtonSize.COMPACT)
)
);
const textInput5 = CardService.newTextInput()
.setFieldName("value5")
.setTitle("Custom button label")
.setHostAppDataSource(
CardService.newHostAppDataSource().setWorkflowDataSource(
CardService.newWorkflowDataSource()
.setIncludeVariables(true)
.setVariableButtonLabel("New button label!")
)
);
var cardSection = CardService.newCardSection()
.addWidget(textInput1)
.addWidget(textInput2)
.addWidget(textInput3)
.addWidget(textInput4)
.addWidget(textInput5)
.setId("section_1");
var card = CardService.newCardBuilder().addSection(cardSection).build();
return card;
}
function onUpdateCardExecuteFunction(event) {
}
Google Workspace verileriyle otomatik tamamlama özelliğini yapılandırma
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 özelliklerini gösteren üç SelectionInput widget'ı içeren bir kart oluşturan onConfig işlevi gösterilmektedir:
JSON
{
"timeZone": "America/Los_Angeles",
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8",
"addOns": {
"common": {
"name": "Autocomplete Demo",
"logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
"useLocaleFromApp": true
},
"flows": {
"workflowElements": [
{
"id": "autocomplete_demo",
"state": "ACTIVE",
"name": "Autocomplete Demo",
"description": "Provide autocompletion in input fields",
"workflowAction": {
"inputs": [
{
"id": "value1",
"description": "A multi-select field with autocompletion",
"cardinality": "SINGLE",
"dataType": {
"basicType": "STRING"
}
}
],
"onConfigFunction": "onConfigAutocomplete",
"onExecuteFunction": "onExecuteAutocomplete"
}
}
]
}
}
}
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
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();
}
Giriş değişkenini doğrulama
En iyi uygulama olarak, kullanıcının uygun bir değer girdiğini doğrulayın. Giriş değişkenini doğrulama başlıklı makaleyi inceleyin.
İlgili konular
- Giriş değişkenini doğrulama
- Çıkış değişkenleri
- Dinamik değişkenler
- Etkinlikleri ve hataları günlüğe kaydetme
- Workspace Studio etkinlik nesneleri