Google Workspace Eklentileri için manifestler

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

Bu dokümanda, bir Google Workspace eklentisi için manifest yapılandırmayla ilgili ayrıntılar açıklanmaktadı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ü altında düzenlenmiştir.

• Apps Komut Dosyası manifest dosyaları hakkında bilgi için Manifest yapısına bakın.
• HTTP uç noktaları ile oluşturulan eklentilerin manifest dosyaları hakkında bilgi için REST Kaynağı: projects.deployments bölümüne bakın

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

Aşağıdaki manifest örneğinde, Google Workspace eklentilerini tanımlayan manifest dosyasının bir bölümü ve aşağıdaki özellikler gösterilmektedir:

• Manifest'in addOns.common bölümü, eklentinin adını, logo URL'sini, renkleri ve diğer genel, ana makineden bağımsız ayarlarını tanımlar.
• Manifest, ortak bir ana sayfayı tanımlamanı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ı aşağıdakileri sağlar:
  • eventOpen ve eventUpdated takvimi tetikleyicileri.
  • (Yalnızca Apps Komut Dosyası) İki Takvim konferans çözümü.
  • İki evrensel işlem.
  • Bir Sürüş onItemsSelectedTrigger.
  • Gmail oluşturma işlemi ve bağlamsal tetikleyici.
  • Dokümanlar linkPreviewTriggersnesnesi. Bu tetikleyici hakkında bilgi edinmek için Akıllı çiplerle bağlantıları önizleme bölümüne bakın.
  • Dokümanlar createActionTriggers nesnesi. Bu tetikleyici hakkında bilgi edinmek için @ menüsünden üçüncü taraf kaynakları oluşturma bölümüne bakın.
  • Dokümanlar, E-Tablolar ve Slaytlar için dosyaya özgü arayüzler.
• oauthScopes alanı, proje için yetkilendirme kapsamlarını ayarlar (genellikle eklentiler için gereklidir).
• (Yalnızca Apps Komut Dosyası) urlFetchWhitelist alanı, getirilen uç noktaların belirtilen bir HTTPS URL önek listesiyle eşleşmesini sağlayan bir alandır. Daha fazla bilgi için URL'leri izin verilenler listesine ekleme bölümünü inceleyin.

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

Not: Manifestler başka bileşenler içerir. addOns alanının altındaki alanlar doğrudan Google Workspace Eklentileriyle ilişkilidir. Bu örnek, tam manifest dosyasının yalnızca bir parçasıdır ve tam olarak 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 listesi

Komut dosyanız veya eklentiniz tarafından erişim için önceden onaylanan belirli URL'leri tanımlamak için izin verilenler listelerini 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, bir test dağıtımı yüklerken isteğe bağlıdır ancak sürümü olan bir dağıtım oluşturduğunuzda zorunludur.

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

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

Not: İzin verilenler listesi, urlFetchWhitelist ifadesinde kullanıldığı şekilde, desteği sonlandırılmış bir terimdir ve izin verilenler listesi ile eş anlamlıdır ve bu terim ile eş anlamlıdır. Daha fazla bilgi için Kapsayıcı dokümanlar yazma bölümüne bakın.

İzin verilenler listenize ön ek ekleme

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

• Her önek geçerli bir URL olmalıdır.
• Her ön ek için http:// değil, https:// kullanılmalıdır.
• Her önek, tam alan adına 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ı ö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 karakteri kullanılabilir. Ancak bu, kullanıcının verilerini riske atabileceği ve eklenti incelemesi sürecini uzatabileceği için önerilmez. Joker karakterleri yalnızca eklenti işlevselliğiniz için gerekiyorsa kullanın.

Bir URL'nin izin verilenler listesindeki bir ön ekle eşleşip eşleşmediğini belirlerken aşağıdaki kurallar geçerli olur:

• Yol eşleştirme büyük/küçük harfe duyarlıdır.
• Önek, URL ile aynıysa eşleşmedir.
• URL, ön ekin aynı veya bir alt öğesiyse eşleşmedir.

Ö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 karakter kullanma

Hem urlFetchWhitelist hem de addOns.common.openLinkUrlPrefixes alanları için alt alan adlarını eşleştirmek üzere tek bir joker karakter (*) kullanabilirsiniz. Birden çok alt alan adını eşleştirmek için birden fazla joker karakter kullanamazsınız. Joker karakter, URL'nin başındaki ön eki 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şmez:

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

Manifest dosyanızı kaydetmeye çalışırken önek kurallarından bazıları zorunlu kılınır. Örneğin, aşağıdaki önekler kaydetmeye çalıştığınızda manifestinizde varsa hataya neden olur:

• https://*.*.example.com/foo (birden fazla joker karakter kullanılamaz)
• https://subdomain.*.example.com/foo (baştaki önek olarak joker karakterler kullanılmalıdır)