Google Workspace eklentileri için manifest'ler

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

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

Google Workspace eklentileri için manifest yapısı

Google Workspace eklentileri, eklentinin görünümü ve davranışıyla ilgili çeşitli özellikleri 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 Komut Dosyası manifest dosyaları hakkında bilgi 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 projects.deployments kaynağına bakın.

Google Chat için manifestler

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

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

• Chat uygulamasının yalnızca Chat kullanıcı arayüzünde görünen adı, logosu ve açıklaması.
• 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ını kullanıyorsa zorunludur)

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

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

Aşağıdaki manifest örneklerinde, bir Google Workspace eklentisini tanımlayan manifest dosyasının bölümü gösterilmektedir. Bu bölüm aşağıdaki yönleri içerir:

• Manifestin addOns.common bölümünde, eklentinin adı, logo URL'si, renkleri ve diğer genel, ana makineden bağımsız ayarları tanımlanır.

• Manifest, ortak bir ana sayfa tanımlar ancak 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ı sağlar:

  • 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ğlamsal tetikleyici.

  • Bir Dokümanlar linkPreviewTriggers nesnesi. Bu tetikleyici hakkında bilgi edinmek için Akıllı çipleri kullanarak bağlantıları önizleme başlıklı makaleyi inceleyin.

  • Bir Dokümanlar createActionTriggers nesnesi. Bu tetikleyici hakkında bilgi edinmek için @ menüsünden üçüncü taraf kaynakları oluşturma başlıklı makaleye bakın.

  • Dokümanlar, E-Tablolar ve Slaytlar için dosyaya özel arayüzler.

  • (Yalnızca HTTP) Yetkilendirme üstbilgisi göndermek ve ayrıntılı izni desteklemek için iki HttpOptions

• oauthScopes alanı, proje için yetkilendirme kapsamlarını ayarlar (Genellikle eklentiler için gereklidir).

• (Yalnızca Apps Komut Dosyası) urlFetchWhitelist alanı, getirilen tüm uç noktaların belirtilen HTTPS URL önekleri listesiyle eşleşmesini sağlayan bir alandır. Daha fazla bilgi için URL'leri izin verilenler listesine ekleme başlıklı makaleyi inceleyin.

Manifest örneklerindeki bağlantılar, Apps Komut Dosyası ve HTTP Google Workspace eklentileri için ilgili manifest referans belgelerindeki alan açıklamalarına yönlendirir.

Not: Manifestler başka bileşenler de içerir. addOns alanındaki alanlar doğrudan Google Workspace eklentileriyle ilgilidir. Bu örnek, tam bir manifest dosyasının yalnızca bir bölümüdür ve tam işlevli 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"
      }
    }
    "httpOptions": {
      "authorizationHeader": "SYSTEM_ID_TOKEN",
      "granularOauthPermissionSupport": "OPT_IN"
    }
  },
  "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

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

Bu alan, test dağıtımı yüklerken isteğe bağlıdır ancak sürüm oluşturulmuş bir dağıtım oluştururken zorunludur.

Komut dosyanız veya eklentiniz aşağıdaki işlemleri yaptığında izin verilenler listelerini kullanırsınız:

• Apps Script UrlFetch hizmetini kullanarak harici bir konumdan (ör. HTTPS uç noktaları) bilgi alır veya getirir. Getirme için URL'leri 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örüntüler (Google dışındaki URL'leri açan veya görüntüleyen Google Workspace eklentileri için zorunludur). URL'lerin açılmasına izin vermek için addOns.common.openLinkUrlPrefixes alanını manifest dosyanıza ekleyin.

Not: urlFetchWhitelist'da kullanılan beyaz liste, izin verilenler listesi ile eş anlamlı olan ve bu terimin yerine kullanılan, 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 önek ekleme

Manifest dosyanızda izin verilenler listelerini belirttiğinizde (addOns.common.openLinkUrlPrefixes veya urlFetchWhitelist alanını ekleyerek) URL öneklerinin bir listesini eklemeniz gerekir. Manifeste eklediğiniz önekler aşağıdaki koşulları karşılamalıdır:

• Her önek geçerli bir URL olmalıdır.
• Her önekte http:// değil, https:// kullanılmalıdır.
• Her önekte tam alan adı olmalıdır.
• Her önekte boş olmayan bir yol olmalıdır. Örneğin, https://www.google.com/ geçerlidir ancak https://www.google.com geçerli değildir.
• URL alt alan adı öneklerini 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 karakter kullanılabilir ancak bu, kullanıcının verilerini riske atabileceğinden ve eklenti inceleme sürecini uzatabileceğinden önerilmez. Yalnızca eklentinizin işlevi gerektiriyorsa joker karakter kullanın.

Bir URL'nin izin verilenler listesindeki bir önekle eşleşip eşleşmediği belirlenirken aşağıdaki kurallar geçerlidir:

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

Örneğin, https://example.com/foo öneki 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

Joker karakterleri kullanma

Hem urlFetchWhitelist hem de addOns.common.openLinkUrlPrefixes alanları için bir alt alan adını eşleştirmek üzere 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 öneki 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 öneki aşağıdaki URL'lerle eşleşmiyor:

• https://subdomain.example.com/bar (sonek eşleşmiyor)
• https://example.com/foo (en az bir alt alan adı bulunmalıdır)

Bazı önek kuralları, manifestinizi kaydetmeye çalıştığınızda zorunlu kılınır. Örneğin, aşağıdaki önekler, kaydetmeye çalıştığınızda manifestinizde bulunuyorsa hataya neden olur:

• https://*.*.example.com/foo (birden fazla joker karakter yasaktır)
• https://subdomain.*.example.com/foo (Joker karakterler, önde gelen bir önek olarak kullanılmalıdır.)