Google Workspace eklentileri için manifest'ler

Eklentiler, uygulama ve işleyişiyle ilgili belirli ayrıntıları yapılandırmak için bir manifest dosyası kullanır.

Bu dokümanda, Google Workspace eklentisi için manifest yapılandırmanın ayrıntıları ele alınmaktadır.

Google Workspace eklentileri için manifest yapısı

Google Workspace eklentileri, eklentinin görünümü ve davranışının çeşitli yönlerini tanımlamak için manifest dosyasını kullanır.

Google Workspace eklentilerinin manifest özellikleri, manifest nesne yapısının addOns bölümünde düzenlenir.

• Apps Script manifest dosyaları hakkında bilgi edinmek için Manifest yapısı başlıklı makaleyi inceleyin.
• HTTP uç noktalarıyla oluşturulan eklentilerin manifest dosyaları hakkında bilgi edinmek için REST Kaynağı: projects.deployments başlıklı makaleyi inceleyin.

Google Chat için manifest'ler

Geliştirici Önizlemesi: Belirli özelliklere erken erişim sağlayan Google Workspace Geliştirici Önizlemesi Programı kapsamında kullanılabilir.

Google Workspace eklentiniz Google Chat'i genişletiyorsa Google Cloud Console'da Google Chat API'yi etkinleştirip yapılandırarak bir Google Chat uygulaması yapılandırmanız gerekir.

Sohbet'te yaygın manifest yapılandırma ayarları (addons.common dahil) yoksayılır. Aşağıdaki Chat ayarlarını yapılandırmak için eklenti manifestini kullanmak yerine Chat API'yi kullanırsınız:

• Chat uygulamasının adı, logosu ve açıklaması (yalnızca Chat kullanıcı arayüzünde görünür).
• Chat uygulaması tetikleyicileri.

Eklentiyi Apps Script'te oluşturduysanız manifest dosyanıza aşağıdaki nesneleri de eklemeniz veya güncellemeniz gerekir:

• addons.chat (Zorunlu)
• oauthScopes (Google Chat uygulamanız OAuth kapsamları kullanıyorsa gereklidir)

Bir eklenti için Chat ayarlarını yapılandırma adımları için Google Chat uygulamasını yapılandırma başlıklı makaleyi inceleyin.

Örnek Google Workspace eklentisi manifest yapılandırması

Aşağıdaki manifest örneğinde, bir manifest dosyasının Google Workspace eklentisini tanımlayan bölümü gösterilmektedir. Bu bölümde aşağıdakiler yer alır:

• Manifestin addOns.common bölümünde, eklentinin adı, logo URL'si, renkleri ve ana makineye bağlı olmayan diğer genel ayarlar tanımlanır.
• Manifest, ortak bir ana sayfanın yanı sıra Takvim, Drive, Dokümanlar, E-Tablolar ve Slaytlar'a özel ana sayfaları da tanımlar. Gmail, varsayılan ana sayfayı kullanır.
• Örnek manifest ayarları şunları etkinleştirir:
  • Takvim eventOpen ve eventUpdated tetikleyicileri.
  • (Yalnızca Apps Komut Dosyası) İki Takvim konferans çözümü.
  • İki evrensel işlem.
  • Drive onItemsSelectedTrigger.
  • Gmail'de ileti oluşturma işlemi ve bağlama dayalı tetikleyici.
  • Dokümanlar linkPreviewTriggers nesnesi. Bu tetikleyici hakkında bilgi edinmek için Akıllı çiplerle bağlantıları önizleme başlıklı makaleyi inceleyin.
  • Dokümanlar createActionTriggers nesnesi. Bu tetikleyici hakkında bilgi edinmek için @ menüsünden üçüncü taraf kaynakları oluşturma başlıklı makaleyi inceleyin.
  • Dokümanlar, E-Tablolar ve Slaytlar için dosyaya özgü arayüzler.
• oauthScopes alanı, proje için yetkilendirme kapsamlarını belirler (Genellikle eklentiler için gereklidir).
• (Yalnızca Apps Komut Dosyası) urlFetchWhitelist alanı, getirilen uç noktaların belirtilen bir HTTPS URL önekleriyle eşleşmesini sağlayan bir alandır. Daha fazla bilgi için URL'leri izin verilenler listesine ekleme başlıklı makaleyi inceleyin.

Örnekteki bağlantılar, Apps Komut Dosyası ve HTTP Google Workspace eklentileri için ilgili manifest referans dokümanlarında bu alanın açıklamalarına yönlendirir.

Not: Manifestler diğer bileşenleri içerir. addOns alanının altındaki alanlar doğrudan Google Workspace eklentileriyle ilgilidir. Bu örnek, tam bir manifest dosyasının yalnızca bir kısmıdır ve tam işlevsel bir manifest değildir.

Apps Komut Dosyası

{
  "addOns": {
    "calendar": {
      "createSettingsUrlFunction": "getConferenceSettingsPageUrl",
      "conferenceSolution": [{
        "id": "my-video-conf",
        "logoUrl": "https://lh3.googleusercontent.com/...",
        "name": "My Video Conference",
        "onCreateFunction": "onCreateMyVideoConference"
      }, {
        "id": "my-streamed-conf",
        "logoUrl": "https://lh3.googleusercontent.com/...",
        "name": "My Streamed Conference",
        "onCreateFunction": "onCreateMyStreamedConference"
      }],
      "currentEventAccess": "READ_WRITE",
      "eventOpenTrigger": {
        "runFunction": "onCalendarEventOpen"
      },
      "eventUpdateTrigger": {
        "runFunction": "onCalendarEventUpdate"
      },
      "eventAttachmentTrigger": {
        "label": "My Event Attachment",
        "runFunction": "onCalendarEventAddAttachment"
      },
      "homepageTrigger": {
        "runFunction": "onCalendarHomePageOpen",
        "enabled": true
      }
    },
    "common": {
      "homepageTrigger": {
        "runFunction": "onDefaultHomePageOpen",
        "enabled": true
      },
      "layoutProperties": {
        "primaryColor": "#ff392b",
        "secondaryColor": "#d68617"
      },
      "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png",
      "name": "Demo Google Workspace Add-on",
      "openLinkUrlPrefixes": [
        "https://mail.google.com/",
        "https://script.google.com/a/google.com/d/",
        "https://drive.google.com/a/google.com/file/d/",
        "https://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "getSettingsCard"
      }, {
        "label": "Open Help URL",
        "openLink": "https://www.example.com/help"
      }],
      "useLocaleFromApp": true
    },
    "drive": {
      "homepageTrigger": {
        "runFunction": "onDriveHomePageOpen",
        "enabled": true
      },
      "onItemsSelectedTrigger": {
        "runFunction": "onDriveItemsSelected"
      }
    },
    "gmail": {
      "composeTrigger": {
        "selectActions": [
          {
            "text": "Add images to email",
            "runFunction": "getInsertImageComposeCards"
          }
        ],
        "draftAccess": "METADATA"
      },
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ]
    },
    "docs": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      },
      "linkPreviewTriggers": [
        {
        "runFunction": "onLinkPreview",
        "patterns": [
            {
              "hostPattern": "example.com",
              "pathPrefix": "example-path"
            }
        ],
        "labelText": "Link preview",
        "localizedLabelText": {
          "es": "Link preview localized in Spanish"
        },
        "logoUrl": "https://www.example.com/images/smart-chip-icon.png"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "exampleFunction",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },
    "slides": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    }
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.addons.current.event.read",
    "https://www.googleapis.com/auth/calendar.addons.current.event.write",
    "https://www.googleapis.com/auth/drive.addons.metadata.readonly",
    "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/script.locale",
    "https://www.googleapis.com/auth/script.scriptapp",
    "https://www.googleapis.com/auth/drive.file",
    "https://www.googleapis.com/auth/documents.currentonly",
    "https://www.googleapis.com/auth/spreadsheets.currentonly",
    "https://www.googleapis.com/auth/presentations.currentonly",
    "https://www.googleapis.com/auth/workspace.linkpreview"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ]
}

HTTP

{
  "addOns": {
    "calendar": {
      "currentEventAccess": "READ_WRITE",
      "eventOpenTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventOpen"
      },
      "eventUpdateTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventUpdate"
      },
      "eventAttachmentTrigger": {
        "label": "My Event Attachment",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventAddAttachment"
      },
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarHomePageOpen",
        "enabled": true
      }
    },
    "common": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDefaultHomePageOpen",
        "enabled": true
      },
      "layoutProperties": {
        "primaryColor": "#ff392b",
        "secondaryColor": "#d68617"
      },
      "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png",
      "name": "Demo Google Workspace Add-on",
      "openLinkUrlPrefixes": [
        "https://mail.google.com/",
        "https://script.google.com/a/google.com/d/",
        "https://drive.google.com/a/google.com/file/d/",
        "https://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getSettingsCard"
      }, {
        "label": "Open Help URL",
        "openLink": "https://www.example.com/help"
      }],
      "useLocaleFromApp": true
    },
    "drive": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveHomePageOpen",
        "enabled": true
      },
      "onItemsSelectedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveItemsSelected"
      }
    },
    "gmail": {
      "composeTrigger": {
        "actions": [
          {
            "label": "Add images to email",
            "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getInsertImageComposeCards"
          }
        ],
        "draftAccess": "METADATA"
      },
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "https://myownpersonaldomain.com/mypage?trigger=onGmailMessageOpen"
        }
      ]
    },
    "docs": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      },
      "linkPreviewTriggers": [
        {
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onLinkPreview",
          "patterns": [
              {
                "hostPattern": "example.com",
                "pathPrefix": "example-path"
              }
          ],
          "labelText": "Link preview",
          "localizedLabelText": {
            "es": "Link preview localized in Spanish"
          },
          "logoUrl": "https://www.example.com/images/smart-chip-icon.png"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCreateAction",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    },
    "slides": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    }
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.addons.current.event.read",
    "https://www.googleapis.com/auth/calendar.addons.current.event.write",
    "https://www.googleapis.com/auth/drive.addons.metadata.readonly",
    "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/script.locale",
    "https://www.googleapis.com/auth/script.scriptapp",
    "https://www.googleapis.com/auth/drive.file",
    "https://www.googleapis.com/auth/documents.currentonly",
    "https://www.googleapis.com/auth/spreadsheets.currentonly",
    "https://www.googleapis.com/auth/presentations.currentonly",
    "https://www.googleapis.com/auth/workspace.linkpreview"
  ]
}

URL'leri izin verilenler listesine ekleme

Komut dosyanız veya eklentiniz tarafından erişim için önceden onaylanmış belirli URL'leri belirtmek üzere izin verilenler listelerini kullanırsınız. İzin verilenler listeleri, kullanıcı verilerinin korunmasına yardımcı olur. Bir izin verilenler listesi tanımladığınızda komut dosyası projeleri, izin verilenler listesine eklenmemiş URL'lere erişemez.

Bu alan, test dağıtımı yüklediğinizde isteğe bağlıdır ancak sürümlü dağıtım oluşturduğunuzda gereklidir.

Komut dosyanız veya eklentiniz aşağıdaki işlemleri gerçekleştirdiğinde izin verilenler listelerini kullanırsınız:

• Apps Script UrlFetch hizmetini kullanarak harici bir konumdan (ör. HTTPS uç noktaları) bilgi alır veya getirir. URL'leri getirme için izin verilenler listesine eklemek üzere manifest dosyanıza urlFetchWhitelist alanını ekleyin.
• Kullanıcı işlemine yanıt olarak bir URL'yi açar veya gösterir (Google dışındaki URL'leri açan veya gösteren Google Workspace eklentileri için gereklidir). URL'leri açma için izin verilenler listesine eklemek üzere manifest dosyanıza addOns.common.openLinkUrlPrefixes alanını ekleyin.

Not: urlFetchWhitelist'te kullanılan beyaz liste, izin verilenler listesi ile eş anlamlı olan ve izin verilenler listesi ile değiştirilen, desteği sonlandırılmış bir terimdir. Daha fazla bilgi için Kapsayıcı dokümanlar yazma başlıklı makaleyi inceleyin.

İzin verilenler listenize ön ek ekleme

Manifest dosyanızda izin verilenler listelerini belirtirken (addOns.common.openLinkUrlPrefixes veya urlFetchWhitelist alanını ekleyerek) URL ön eklerinin listesini eklemeniz gerekir. Manifest dosyasına eklediğiniz ön ekler aşağıdaki koşulları karşılamalıdır:

• Her ön ek geçerli bir URL olmalıdır.
• Her ön ek için http:// yerine https:// kullanılmalıdır.
• Her ön ek tam bir alana sahip olmalıdır.
• Her ön ekin boş olmayan bir yolu olmalıdır. Örneğin, https://www.google.com/ geçerlidir ancak https://www.google.com geçerli değildir.
• URL alt alan adı ön eklerini eşleştirmek için joker karakterler kullanabilirsiniz.
• Tüm bağlantıları eşleştirmek için addOns.common.openLinkUrlPrefixes alanında tek bir * joker karakteri kullanılabilir ancak bu, kullanıcının verilerini riske atabileceği ve eklenti inceleme sürecini uzatabileceği için önerilmez. Yalnızca eklenti işleviniz gerektiriyorsa joker karakter kullanın.

Bir URL'nin izin verilenler listesindeki bir ön ek ile eşleşip eşleşmediği belirlenirken aşağıdaki kurallar geçerli olur:

• Yol eşleştirmesi büyük/küçük harfe duyarlıdır.
• Ön ek, URL ile aynıysa eşleşme vardır.
• URL aynıysa veya ön ekin alt öğesiyse eşleşme vardır.

Örneğin, https://example.com/foo ön eki aşağıdaki URL'lerle eşleşir:

• https://example.com/foo
• https://example.com/foo/
• https://example.com/foo/bar
• https://example.com/foo?bar
• https://example.com/foo#bar

Karıştırıcı karakterleri kullanma

Hem urlFetchWhitelist hem de addOns.common.openLinkUrlPrefixes alanlarında bir alt alan adını eşleştirmek için tek bir joker karakter (*) kullanabilirsiniz. Birden fazla alt alan adını eşleştirmek için birden fazla joker karakter kullanamazsınız ve joker karakter, URL'nin ön ekini temsil etmelidir.

Örneğin, https://*.example.com/foo ön eki aşağıdaki URL'lerle eşleşir:

• https://subdomain.example.com/foo
• https://any.number.of.subdomains.example.com/foo

https://*.example.com/foo ön eki aşağıdaki URL'lerle eşleşmez:

• https://subdomain.example.com/bar (son ek uyuşmazlığı)
• https://example.com/foo (en az bir alt alan adı bulunmalıdır)

Ön ek kurallarının bazıları, manifest dosyanızı kaydetmeye çalıştığınızda uygulanır. Örneğin, kaydetmeye çalıştığınızda manifest dosyanızda aşağıdaki ön ekler varsa hata oluşur:

• https://*.*.example.com/foo (birden fazla joker karakter yasaktır)
• https://subdomain.*.example.com/foo (joker karakterler, ön ek olarak kullanılmalıdır)