Etkileşimli bir Google Chat uygulamasını Google Workspace eklentisine dönüştürme

Google Chat uygulaması hızlı başlangıç kılavuzuna dayalı olanlar gibi Google Chat API etkileşim etkinliklerini kullanan bir Google Chat uygulaması oluşturup yayınladıysanız bu sayfada, uygulamayı Google Chat'i genişleten bir Google Workspace eklentisine nasıl dönüştüreceğiniz açıklanmaktadır.

Dönüştürme işlemiyle Google Chat uygulamanız, Google Workspace eklentileri çerçevesini kullanabilir. Bu sayede Google Chat'te ve Google Workspace'te entegrasyon ve özellikler için yeni olanaklar sunulur. Örneğin, Google Workspace Marketplace üzerinden tek bir Google Workspace eklentisi dağıtabilirsiniz. Bu eklenti, Chat uygulamalarını Gmail, Takvim ve Dokümanlar gibi diğer Google Workspace ana uygulamalarıyla birlikte kullanmanıza olanak tanır.

Sınırlamalar

Dönüşümü başlatmadan önce, Google Chat'i genişleten Google Workspace eklentilerinin sınırlamalarını inceleyerek Google Chat uygulamanızın temel işlevselliği kaybetmeden dönüştürülebileceğinden emin olun.

1. adım: Mevcut Google Chat uygulama kodunuzu kopyalayın

Dönüşüm işlemi için kod değişiklikleri yapılması gerekir. Yayındaki Google Chat uygulamanızın etkilenmemesi için kodunuzun bir kopyasını oluşturup bu kopya üzerinde çalışın.

2. adım: Kopyalanan kodu değiştirin

Google Chat'in kullanımını genişleten Google Workspace eklentileri, Chat API etkileşim etkinlikleriyle oluşturulan Google Chat uygulamalarına kıyasla farklı istek ve yanıt yapıları kullanır. İstekler ve yanıtlar için Google Chat API'leri Event yerine Google Workspace eklentisini EventObject kullanmak üzere kodunuzu güncellemeniz gerekir. Kodunuzu değiştirmek için Kod dönüştürme kılavuzunu kullanın.

3. adım: Test kullanıcıları için Google Workspace eklenti yapılandırmasını etkinleştirin

Google Chat uygulamanız için Google Workspace eklenti ayarlarını yapılandırmak üzere Google Cloud Console'u kullanın:

1. Google Cloud Console'da Google Chat API yapılandırma sayfasına gidin.

   Google Chat API yapılandırma sayfasına gitme

2. Etkileşimli Özellikler bölümünde Etkileşimli özellikleri etkinleştir'i açın.

3. Google Workspace eklentisine dönüştür bölümünde Eklentiye dönüştür'ü tıklayın.

4. Eklenti yapılandırma ayarlarını etkinleştir'i etkinleştirin.

5. Görünürlük bölümüne test kullanıcılarınızın e-posta adreslerini ekleyin.

6. Gerekirse Bağlantı Ayarları'nı, 2. adımda kopyaladığınız ve değiştirdiğiniz Google Chat uygulama kodunuzun dağıtım uç noktası URL'si veya Apps Komut Dosyası dağıtım kimliği ile güncelleyin.

7. Kaydet ve test et'i tıklayın.

4. adım: Dönüştürülen uygulamayı test edin

3. adımda yapılandırılan test kullanıcı hesaplarını kullanarak Google Workspace eklentisinin işlevselliğini kapsamlı bir şekilde test edin. Tüm özellikleri ve etkileşimleri doğrulayın.

5. adım: Dönüşümü tüm kullanıcılar için tamamlayın

Dönüştürülen Google Workspace eklentisinin doğru şekilde çalıştığını doğruladıktan sonra eklentiyi tüm kullanıcıların kullanımına sunabilirsiniz.

1. Google Cloud Console'da Google Chat API yapılandırma sayfasına gidin.

   Google Chat API yapılandırma sayfasına gitme

2. Etkileşimli Özellikler bölümünde Eklentiye dönüştür'ü tıklayın. Bir yan panel açılır.

3. Yan panelde Eklentiye dönüştür'ü tıklayın.

4. Proje kimliğinizi yazın ve Dönüştür'ü tıklayın.

Google Chat uygulamanız artık Google Chat'i genişleten bir Google Workspace eklentisidir.

İsteğe bağlı: Kullanılmayan Google Cloud kaynaklarını temizleme veya boşaltma

İsteğe bağlı olarak, Google Chat uygulamanızı Google Workspace eklentisine dönüştürdükten sonra, artık kullanılmayan Google Chat uygulaması tarafından kullanılan kaynaklar için Google Cloud hesabınıza ücret yansıtılmaması amacıyla bu kaynakları devre dışı bırakabilirsiniz.

Kod dönüştürme kılavuzu

Bu bölümde, Google Chat API etkileşimi Event biçimi ile Google Workspace eklentisi EventObject biçimi arasındaki eşleme ayrıntılı olarak açıklanmaktadır.

İstek eşleme

Aşağıdaki tabloda, Google Chat API'deki alanların Event Google Workspace eklentisindeki karşılık gelen alanlarla nasıl eşlendiği gösterilmektedir EventObject.

Kullanım alanına göre eşleme isteğinde bulunma

Aşağıdaki tabloda, Chat API etkileşim etkinlikleriyle oluşturulan Google Chat uygulamaları ile Google Chat'i genişleten Google Workspace eklentileri arasındaki yaygın kullanım alanlarına yönelik istek yüklerindeki farklılıklar gösterilmektedir.

{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}

{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}

{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}

{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}

{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}

{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}

{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}

{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}

{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}

{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}

{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}

{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}

{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}

{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}

{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}

{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}

{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}

{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}

{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}

{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

Kullanım alanına göre yanıt eşleme

Google Chat'i genişleten Google Workspace eklentileri, Message nesnesi yerine işlemler döndürür. Aşağıdaki tabloda, Google Chat API Message yanıt türleri ile bunların Google Workspace eklentisi işlem karşılıkları eşlenmiştir.

{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}

{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

Dönüşümden önce oluşturulan mesajlardaki kart etkileşimlerini yönetme

Bir HTTP Google Chat uygulamasını Google Workspace eklentisine dönüştürdüğünüzde, dönüştürme işleminden önce oluşturulan iletilerdeki kart etkileşimleri özel işlem gerektirir. Eklentiler, kartın action.function için tam bir HTTP URL'si kullanırken Google Chat API etkileşim etkinlikleriyle oluşturulan Chat uygulamaları bir işlev adı kullanır. Aşağıdaki tabloda bu farklılıklar özetlenmektedir.

{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}

{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

Dönüşümden önce oluşturulan mesajlarda kart etkileşimlerinin çalışır durumda olmasını sağlamak için Google Chat API yapılandırma sayfasında bir Kart Etkileşimi URL'si yapılandırın.

Bu URL yalnızca uygulamanızı dönüştürmeden önce oluşturulan mesajlardaki etkileşimler için kullanılır. Bir kullanıcı bu mesajlardan biriyle etkileşimde bulunduğunda orijinal action.function değeri, __action_method_name__ adlı bir parametre olarak iletilir.

Örnek: Kart tıklaması

Kart Etkileşimi URL'sini https://.../card-interaction-handler olarak yapılandırdıysanız ve bir kullanıcı, aşağıdaki işlemle birlikte geçmiş bir iletideki bir kartı tıklarsa:

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

Bir etkinlik, yapılandırılmış Kart Etkileşimi URL'nize aşağıdaki biçimde iletilir:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

Örnek: Çoklu seçim menüsü

Bir kullanıcı, harici veri kaynağı içeren çoklu seçim menüsüyle etkileşim kurarsa:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

Bir etkinlik, yapılandırılmış Kart Etkileşimi URL'nize aşağıdaki biçimde iletilir:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

HTTP tetikleyicileriniz için Tüm tetikleyicilerde ortak HTTP uç noktası URL'si kullan seçeneğini etkinleştirirseniz ortak URL, Düğme Tıklandı etkinlikleri için de kullanılır.

Chat'i genişleten HTTP Google Workspace eklentileri için istekleri doğrulama

HTTP tabanlı Google Chat uygulamalarında, isteklerin Google'dan geldiğini doğrulama mantığı, Google Workspace eklentisine dönüştürülürken güncellenmelidir.

• Google Chat API etkileşim etkinliği HTTP Google Chat uygulaması doğrulaması: Google Chat'ten gelen istekleri doğrulama
• Google Workspace eklentisi HTTP doğrulaması: Google'dan gelen istekleri doğrulama

İstek doğrulama ile ilgili temel farklar şunlardır:

Google Workspace eklentinizin benzersiz hizmet hesabı e-posta adresini, Google Cloud Console'daki Google Chat API yapılandırma sayfasının Google Workspace eklentilerine dönüştür bölümünde bulabilirsiniz.

Yükseltilmiş Google Workspace eklentinizdeki istekleri doğrulamak için:

1. Cloud Run işlevlerini kullanıyorsanız eklenti başına hizmet hesabına roles/cloudfunctions.invoker rolünü verin. IAM ile erişimi yetkilendirme başlıklı makaleyi inceleyin.
2. Taşıyıcı jetonun imzasını doğrulamak için jeton doğrulama kodunuzu Google Workspace eklenti hizmeti hesabı e-posta adresini kullanacak şekilde güncelleyin. Google'dan gelen istekleri doğrulama başlıklı makaleyi inceleyin.