DocuSign

使用 DocuSign 連接器，在 DocuSign 執行讀取作業。

事前準備

使用 DocuSign 連接器前，請先完成下列工作：

• 在 Google Cloud 專案中：
  • 請確認已設定網路連線。如要瞭解網路模式，請參閱「網路連線」。
  • 將 roles/connectors.admin IAM 角色授予設定連接器的使用者。
  • 將下列 IAM 角色授予要用於連接器的服務帳戶：
    • roles/secretmanager.viewer
    • roles/secretmanager.secretAccessor

    服務帳戶是特殊的 Google 帳戶類型，主要用於代表非人類使用者，需要通過驗證並取得授權，才能存取 Google API 中的資料。如果您沒有服務帳戶，則必須建立服務帳戶。連接器和服務帳戶必須屬於同一個專案。詳情請參閱「建立服務帳戶」。

  • 啟用下列服務：
    • secretmanager.googleapis.com (Secret Manager API)
    • connectors.googleapis.com (Connectors API)

    如要瞭解如何啟用服務，請參閱「啟用服務」。

  如果專案先前未啟用這些服務或權限，系統會在設定連接器時提示您啟用。

設定連接器

連結是資料來源專屬。也就是說，如果您有多個資料來源，就必須為每個資料來源建立個別連線。如要建立連線，請按照下列步驟操作：

1. 在 Cloud 控制台中，前往「Integration Connectors」>「Connections」頁面，然後選取或建立 Google Cloud 專案。

   前往「Connections」(連線) 頁面

2. 按一下「+ 新建」，開啟「建立連線」頁面。
3. 在「Location」(位置) 部分，選擇連線位置。
   1. 「區域」：從下拉式選單中選取位置。

      如需所有支援區域的清單，請參閱「位置」。

   2. 點按「下一步」。
4. 在「Connection Details」(連線詳細資料) 部分，完成下列操作：
   1. 連接器：從可用連接器的下拉式清單中，選取「DocuSign」。
   2. 連接器版本：從可用版本的下拉式清單中選取連接器版本。
   3. 在「Connection Name」(連線名稱) 欄位中，輸入連線執行個體的名稱。

      連線名稱必須符合下列條件：

      • 連線名稱可以使用英文字母、數字或連字號。
      • 英文字母必須為小寫。
      • 連線名稱的開頭須為英文字母，結尾則須為英文字母或數字。
      • 連線名稱不得超過 49 個字元。
   4. 視需要輸入連線執行個體的說明。
   5. 視需要啟用「Cloud logging」(Cloud Logging)，然後選取記錄層級。記錄層級預設為 Error。
   6. 服務帳戶：選取具備必要角色的服務帳戶。
   7. 如果您使用 DocuSign 沙箱帳戶，可以視需要選取「UseSandbox」UseSandbox。
   8. 視需要設定「Connection node settings」(連線節點設定)：
      • 「Minimum number of nodes」(節點數量下限)：輸入連線節點數量下限。
      • Maximum number of nodes (節點數量上限)：輸入連線節點數量上限。

      節點是用來處理交易的連線單位 (或副本)。處理的交易量越多，就需要越多節點，反之亦然。如要瞭解節點對連接器定價的影響，請參閱「連線節點定價」。如未輸入任何值，節點數量下限預設為 2 (可提高可用性)，節點數量上限則預設為 50。

   注意：只有即付即用客戶可以自訂連線節點值。
   9. (選用) 按一下「+ 新增標籤」，以鍵/值組合的形式為連線新增標籤。
   10. 點按「下一步」。
5. 在「Authentication」(驗證) 部分，輸入驗證詳細資料。
   1. 選取「Authentication type」(驗證類型)，然後輸入相關詳細資料。

      DocuSign 連線支援下列驗證類型：

      • OAuth 2.0 - 授權碼
      • OAuth 2.0 - JWT 持有者

   如要瞭解如何設定這些驗證類型，請參閱「設定驗證」。

   2. 點按「下一步」。
6. 查看：查看連線和驗證詳細資料。
7. 點選「建立」。

設定驗證機制

根據要使用的驗證方式輸入詳細資料。

• OAuth 2.0 - 授權碼
  • 用戶端 ID：用於要求存取權杖的用戶端 ID。
  • Scopes：以半形逗號分隔的所需範圍清單。
  • 用戶端密鑰：Secret Manager 密鑰，內含您建立的連結應用程式用戶端密鑰。
  • 授權網址：輸入授權網址，例如正式版帳戶的 https://account.docusign.com/oauth/auth 或沙箱帳戶的 https://account-d.docusign.com/oauth/auth。
  設定第三方 OAuth 應用程式時，請使用這個授權重新導向 URI (回呼網址)：

  https://console.cloud.google.com//connectors/oauth?project=PROJECT_ID

  將 PROJECT_ID 替換為 Google Cloud 專案 ID。

• OAuth 2.0 - JWT Bearer
  • Connected App Consumer Key：您為建立的連結應用程式提供的用戶端金鑰。
  • 使用者名稱：與您建立的連結應用程式相關聯的使用者名稱。
  • 私密金鑰：Secret Manager 密鑰，內含私密金鑰檔案的內容。私密金鑰應與提供給連接器的公開金鑰/憑證相符。

連線設定範例

本節列出建立連線時，您設定的各個欄位範例值。

OAuth 2.0 - 授權碼連線類型

欄位名稱	詳細資料
位置	us-central1
連接器	DocuSign
連接器版本	1
連線名稱	gcp-docusign-new-auth
啟用 Cloud Logging	否
UseSandbox	是
服務帳戶	[e-mail]
驗證	OAuth 2.0 - 授權碼
用戶端 ID	67dxxxxx-xxxx-xxxx-xxxx-xxxxxxxcb79
範圍	signature
用戶端密鑰	CLIENT_SECRET
Secret 版本	1
授權網址	https://account-d.docusign.com/oauth/auth

OAuth 2.0 - JWT Bearer 連線類型

欄位名稱	詳細資料
位置	us-central1
連接器	DocuSign
連接器版本	1
連線名稱	gcp-docusign-token
啟用 Cloud Logging	否
UseSandbox	是
服務帳戶	[e-mail]
驗證	OAuth 2.0 - JWT 持有者
連結的應用程式用戶端金鑰	67dxxxxx-xxxx-xxxx-xxxx-xxxxxxxcb79
使用者名稱	USER_NAME
私密金鑰	PRIVATE_KEY
Secret 版本	1

實體、作業和動作

所有 Integration Connectors 都會為已連結應用程式的物件提供抽象層。您只能透過這個抽象層存取應用程式的物件。抽象化會以實體、作業和動作的形式呈現。

注意：您可以在連接器工作中查看連接器的實體、作業和動作。

• 實體：實體可視為連結應用程式或服務中的物件，或屬性集合。實體的定義因連接器而異。舉例來說，在資料庫連接器中，資料表是實體；在檔案伺服器連接器中，資料夾是實體；在訊息系統連接器中，佇列是實體。

  不過，連接器可能不支援或沒有任何實體，在這種情況下，Entities 清單會是空白。

• 作業：作業是指可對實體執行的活動。您可以對實體執行下列任一操作：
  • 列出
  • 取得
  • 建立
  • 更新
  • 刪除

  從可用清單中選取實體後，系統會產生該實體可用的作業清單。如要進一步瞭解作業，請參閱連接器工作的實體作業。不過，如果連接器不支援任何實體作業，Operations 清單就不會列出這類不支援的作業。

• 動作：動作是透過連接器介面提供給整合的第一類函式。動作可讓您變更一或多個實體，且因連接器而異。一般來說，動作會有一些輸入參數和一個輸出參數。不過，連接器可能不支援任何動作，在這種情況下，Actions 清單會是空白。

注意：所有實體和動作都會有相關聯的結構定義。舉例來說，動作結構定義會包含參數詳細資料，例如參數名稱和對應的資料類型。連線會在執行階段從後端擷取實體和動作的結構定義 (中繼資料)。如果結構定義有任何更新，現有連結不會自動反映這些更新，您必須手動重新整理結構定義。如要重新整理連線的結構定義，請開啟連線的「Connection details」(連線詳細資料) 頁面，然後按一下「Refresh connection schema」(重新整理連線結構定義)。

系統限制

DocuSign 連接器每秒可處理 3 筆交易 (以節點為單位)，並會限制超出此上限的交易。根據預設，Integration Connectors 會為連線分配 2 個節點 (以提高可用性)。

如要瞭解 Integration Connectors 的限制，請參閱「限制」。

注意：Integration Connectors 節點數量會根據用量動態自動調度資源。不過，如果您想為大量資料預留容量，而不等待自動調度資源，可以調整連線的節點值下限。如要為連線處理更多交易，則需要更多節點。反之，如果連線處理的交易量較少，則需要的節點也較少。如要設定節點值，請按照下列步驟操作：

• 如果您是即付即用客戶，請在編輯連線頁面中設定節點值的最小值和最大值。
• 如果您是訂閱制客戶，請聯絡支援團隊。

節點可處理的交易數量上限取決於多項因素。因此，建議您先確認後端系統是否已妥善設定，可處理所需流量，再調整節點數量下限，提高處理量。

動作

本節列出 DocuSign 連線支援的所有動作。

CreateAndSendEnvelope 動作

建立並傳送信封，或建立信封草稿。

CreateAndSendEnvelope 動作的輸入參數

參數名稱	資料類型	必填	說明
FileName	字串	是	文件名稱。
DocumentId	字串	是	文件 ID。
EmailSubject	字串	是	電子郵件的主旨行。
內容	字串	是	檔案中的內容。
SignersEmail	字串	否	文件簽署人的電子郵件 ID。
SignersRecipientId	字串	否	簽署人的收件者 ID。
CcRecipientId	字串	否	電子郵件副本收件者的 ID。
CcEmail	字串	否	電子郵件副本收件者的電子郵件 ID。
狀態	字串	否	信封狀態。將狀態設為「sent」，即可將信封傳送給收件者。
CustomFieldAggregate	字串	否	您可以使用下列資料欄：CustomFieldName、CustomFieldId、CustomFieldShow、CustomFieldRequired、CustomFieldValue、CustomFieldConfiguration 和 CustomFieldListItems。
SignersName	字串	否	文件簽署者的姓名。
CcName	字串	否	副本收件者的名稱。

如需設定 CreateAndSendEnvelope 動作的範例，請參閱「範例」。

動作範例

本節說明如何執行這個連接器中的部分動作。

範例 - CreateAndSendEnvelope

這項操作會建立並傳送信封，或建立信封草稿。

1. 在「Configure connector task」對話方塊中，按一下「Actions」。
2. 選取「CreateAndSendEnvelope」動作，然後按一下「完成」。
3. 在「Connectors」(連接器) 工作的「Task Input」(工作輸入) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
   "EmailSubject": "Please Sign this Document",
   "FileName": "test.txt\ntest.pdf",
   "SignersEmail": "[e-mail]",
   "SignersRecipientId": "53386460",
   "CcRecipientId": "67173451",
   "CcEmail": "[e-mail]",
   "DocumentId": "1",
   "Status": "sent",
   "CustomFieldAggregate": "CustomFieldName",
   "ContentBytes": "abcd***",
   "HasBytes": true,
   "SignersName": "\"test\"",
   "CcName": "\"test\"",
   "Content": "test content in file"
   }
   

如果動作成功，連接器工作的 connectorOutputPayload 回應參數值會類似下列內容：

 [{
"Success":"true",
"envelopeid":"542a77ff-b533-4b39-9d82-e397ef5a70c9",
"uri":"/envelopes/542a77ff-b533-4b39-9d82-e397ef5a70c9",
"statusdatetime":"2025-04-09T12:33:47.1130000Z",
"status":"sent",
"customfieldaggregate": "CustomFieldName"
}]

實體作業範例

本節說明如何在這個連接器中執行部分實體作業。

實體 ID 的值應直接傳遞，例如 16ab549b-95d7-47cb-b557-c2476ef62d9d。ID 16ab549b-95d7-47cb-b557-c2476ef62d9d 是必須傳遞的不重複主鍵值。

範例 - 實體「帳戶」的 LIST 作業

1. 在「Configure connector task」對話方塊中，按一下「Entities」。
2. 從「Entity」清單中選取「帳戶」。
3. 選取 LIST 作業，然後按一下「Done」(完成)。

範例 - 實體「Documents」的 LIST 作業

1. 在「Configure connector task」對話方塊中，按一下「Entities」。
2. 從「Entity」清單中選取「文件」。
3. 選取 LIST 作業，然後按一下「Done」(完成)。

範例 - 實體「Envelopes」的 LIST 作業

1. 在「Configure connector task」對話方塊中，按一下「Entities」。
2. 從 Entity 清單中選取「Envelopes」。
3. 選取 LIST 作業，然後按一下「Done」(完成)。

範例：實體「Folders」的 LIST 作業

1. 在「Configure connector task」對話方塊中，按一下「Entities」。
2. 從「Entity」清單中選取「資料夾」。
3. 選取 LIST 作業，然後按一下「Done」(完成)。

範例 - 實體「群組」的 LIST 作業

1. 在「Configure connector task」對話方塊中，按一下「Entities」。
2. 從「Entity」清單中選取「群組」。
3. 選取 LIST 作業，然後按一下「Done」(完成)。

範例 - 實體「使用者」的 LIST 作業

1. 在「Configure connector task」對話方塊中，按一下「Entities」。
2. 從 Entity 清單中選取「使用者」。
3. 選取 LIST 作業，然後按一下「Done」(完成)。

您也可以對下列實體執行 LIST 作業：

• UserInfo
• UserSignatures
• 工作區
• 收件者
• AccountBrands
• AccountCustomFields
• EnvelopeTemplates
• EnvelopeAttachments
• EnvelopeConsumerDisclosures
• CloudStorageProviders
• CustomTabs
• 門鎖
• GroupBrands
• GroupUsers
• PowerForms
• RecipientTabs
• SigningGroups
• SigningGroupUsers
• 範本

範例 - 取得實體「帳戶」的單一記錄

1. 在「Configure connector task」對話方塊中，按一下「Entities」。
2. 從「Entity」清單中選取「帳戶」。
3. 選取 GET 作業，然後按一下「Done」(完成)。
4. 如要設定實體 ID，請在「Data Mapping」(資料對應) 的「Data Mapper」(資料對應器) 區段中，按一下「Open Data Mapping Editor」(開啟資料對應編輯器)，然後在「Input Value」(輸入值) 欄位中輸入 2.4578824E7，並選擇 EntityId 做為本機變數。

範例 - 取得實體「Documents」的單一記錄

1. 在「Configure connector task」對話方塊中，按一下「Entities」。
2. 從「Entity」清單中選取「文件」。
3. 選取 LIST 作業，然後按一下「Done」(完成)。
4. 如要設定篩選子句，請在「Data Mapping」的「Data Mapper」部分，按一下「Open Data Mapping Editor」，然後在「Input Value」欄位中輸入 Type='envelopes' AND Id='8e18be14-3254-4cbe-947d-f0d1cd62f5f8'，並選擇篩選子句做為本機變數。

範例 - 取得實體「Envelopes」的單一記錄

1. 在「Configure connector task」對話方塊中，按一下「Entities」。
2. 從 Entity 清單中選取「Envelopes」。
3. 選取 GET 作業，然後按一下「Done」(完成)。
4. 如要設定實體 ID，請在「Data Mapping」(資料對應) 的「Data Mapper」(資料對應器) 區段中，按一下「Open Data Mapping Editor」(開啟資料對應編輯器)，然後在「Input Value」(輸入值) 欄位中輸入 8e18be14-3254-4cbe-947d-f0d1cd62f5f87，並選擇 EntityId 做為本機變數。

範例 - 取得實體「Folders」的單一記錄

1. 在「Configure connector task」對話方塊中，按一下「Entities」。
2. 從「Entity」清單中選取「資料夾」。
3. 選取 GET 作業，然後按一下「Done」(完成)。
4. 如要設定實體 ID，請在「Data Mapping」(資料對應) 的「Data Mapper」(資料對應器) 區段中，按一下「Open Data Mapping Editor」(開啟資料對應編輯器)，然後在「Input Value」(輸入值) 欄位中輸入 05f76d13-a513-492b-8c58-176702768db0，並選擇 EntityId 做為本機變數。

範例 - 取得實體「群組」的單一記錄

1. 在「Configure connector task」對話方塊中，按一下「Entities」。
2. 從「Entity」清單中選取「群組」。
3. 選取 GET 作業，然後按一下「Done」(完成)。
4. 如要設定實體 ID，請在「Data Mapping」的「Data Mapper」部分，按一下「Open Data Mapping Editor」，然後在「Input Value」欄位中輸入 1.4167231E7，並選擇 EntityId 做為本機變數。

範例 - 取得實體「使用者」的單一記錄

1. 在「Configure connector task」對話方塊中，按一下「Entities」。
2. 從 Entity 清單中選取「使用者」。
3. 選取 GET 作業，然後按一下「Done」(完成)。
4. 如要設定實體 ID，請在「Data Mapping」的「Data Mapper」部分，按一下「Open Data Mapping Editor」，然後在「Input Value」欄位中輸入 16ab549b-95d7-47cb-b557-c2476ef62d9d，並選擇 EntityId 做為本機變數。

您也可以對下列實體執行 GET 作業：

• UserInfo
• UserSignatures
• 工作區
• 收件者
• AccountBrands
• AccountCustomFields
• EnvelopeTemplates
• EnvelopeAttachments
• EnvelopeConsumerDisclosures
• CloudStorageProviders
• CustomTabs
• 門鎖
• GroupBrands
• GroupUsers
• RecipientTabs
• SigningGroups
• SigningGroupUsers
• 範本

使用 Terraform 建立連線

您可以使用 Terraform 資源建立新連線。

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。

如要查看用於建立連線的 Terraform 範本範例，請參閱範本範例。

使用 Terraform 建立這項連線時，必須在 Terraform 設定檔中設定下列變數：

參數名稱	資料類型	必填	說明
proxy_enabled	BOOLEAN	否	勾選這個核取方塊，即可為連線設定 Proxy 伺服器。
proxy_auth_scheme	ENUM	否	用於向 ProxyServer Proxy 驗證的驗證類型。支援的值：BASIC、DIGEST、NONE
proxy_user	STRING	否	用於向 ProxyServer Proxy 進行驗證的使用者名稱。
proxy_password	SECRET	否	用於向 ProxyServer Proxy 進行驗證的密碼。

在整合作業中使用 DocuSign 連線

建立連線後，您可以在 Apigee Integration 和 Application Integration 中使用該連線。您可以透過連接器工作，在整合中使用連線。

• 如要瞭解如何在 Apigee Integration 中建立及使用連接器工作，請參閱「連接器工作」。
• 如要瞭解如何在 Application Integration 建立及使用連接器工作，請參閱「連接器工作」。

向 Google Cloud 社群尋求協助

您可以在 Google Cloud 社群的 Cloud 論壇中，發布問題並討論這個連接器。

後續步驟

• 瞭解如何暫停及恢復連線。
• 瞭解如何監控連接器用量。
• 瞭解如何查看連接器記錄。