Zendesk

設定驗證機制

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

• 使用者名稱和密碼 (已淘汰)
  • 使用者名稱：用於連線的 Zendesk 使用者名稱。
  • 密碼：Secret Manager 密鑰，內含與 Zendesk 使用者名稱相關聯的密碼。
• API 權杖
  • 使用者：用於驗證的 Zendesk 使用者帳戶。
  • API 權杖：已驗證使用者的 API 權杖。
  • 密鑰版本：密鑰的密鑰版本。
• OAuth 2.0 - 授權碼
  • 用戶端 ID：連接器為您建立的應用程式提供的用戶端 ID。
  • 範圍：以半形逗號分隔的所需範圍清單。
  • 用戶端密鑰：Secret Manager 密鑰，內含您所建立已連結應用程式的用戶端密鑰。
  • 密鑰版本：密鑰的密鑰版本。
  • 授權網址：在 Zendesk 執行個體中建立用戶端時產生的授權網址。

設定事件訂閱

如果您已啟用事件訂閱功能，請在「Event Subscription Details」(事件訂閱詳細資料) 區段中輸入下列值：

1. 選取「目的地類型」。
   • 主機位址：在「host」欄位中輸入後端系統的註冊網址。
2. 選取「API Token」(API 權杖) 做為驗證類型。請勿選取「使用者名稱和密碼」。
3. 輸入驗證詳細資料。
   1. 使用者：用於驗證的 Zendesk 使用者帳戶。
   2. API 權杖：已驗證使用者的 API 權杖。
   3. 密鑰版本：密鑰的密鑰版本。
4. 如要將額外資訊附加至後端系統的回應，請選取「啟用資料充實」。

   額外資訊是針對您設定事件的實體提供。詳情請參閱「事件通知中的資料充實」。

5. 選取「啟用私人連線」，在後端應用程式和連線之間建立安全連線。如果選取這個選項，建立連線後必須執行額外設定步驟。詳情請參閱「活動訂閱的私人連線」。
6. 輸入 dead-letter 設定。如果設定 dead-letter，連線會將未處理的事件寫入指定的 Pub/Sub 主題。輸入下列詳細資料：
   1. 無法傳送的訊息專案 ID： 您已設定無法傳送的訊息 Pub/Sub 主題的 Google Cloud 專案 ID。
   2. 無效信件主題： 要寫入未處理事件詳細資料的 Pub/Sub 主題。
7. 如要使用 Proxy 連線至後端 (適用於事件訂閱)，請輸入下列詳細資料：
1. Proxy SSL Type：連線至 Proxy 伺服器時要使用的 SSL 類型。選取下列任一驗證類型：
   • 「Always」(一律)：連線一律啟用 SSL，以訂閱事件。
   • 「永不」：事件訂閱的連線未啟用 SSL。
2. Proxy Auth Scheme：選取要用於 Proxy 伺服器驗證的驗證類型。 支援的驗證類型如下：
   • 基本：基本 HTTP 驗證。
3. Proxy 使用者：輸入要用於 Proxy 伺服器驗證的使用者名稱。
4. Proxy 密碼：選取使用者密碼的 Secret Manager 密鑰。
5. 密鑰版本：選取密鑰版本。
6. 在「Proxy 伺服器」部分，輸入 Proxy 伺服器的詳細資料。
   1. 按一下「+ 新增目的地」，然後選取「目的地類型」為「主機地址」。
   2. 輸入 Proxy 伺服器的主機名稱或 IP 位址，以及 Proxy 伺服器的通訊埠號碼。

連線設定範例

基本驗證連線類型 (已淘汰)

API 權杖連線類型

OAuth 2.0 - 授權碼連線類型

系統預設會使用 SSL 連線至 Zendesk，如果您使用標準 Zendesk 網址 (例如 https://yoursubdomain.zendesk.com)，則不需要額外設定。

實體、作業和動作

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

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

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

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

  從可用清單中選取實體，系統會產生該實體可用的作業清單。如需作業的詳細說明，請參閱連線器工作中的實體作業。 不過，如果連接器不支援任何實體作業，Operations 清單就不會列出這類不支援的作業。

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

系統限制

Zendesk 連接器每秒可處理 5 筆交易，每個節點也是如此，且會節流任何超出此限制的交易。根據預設，Integration Connectors 會為連線分配 2 個節點 (提高可用性)。

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

動作

Zendesk 連接器提供多種動作，可根據 ticket ID 管理支援單。如要瞭解如何設定動作，請參閱動作範例。

動作範例

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

範例 - 刪除票卡

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

   {
     "Id": "18"
   }

這個範例會永久刪除票券。如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似以下內容：

[{
  "Success": "true"
}] 

範例 - 合併工單

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

   {
     "Id": "25",
     "Id": "26"
   }

這個範例會合併這兩張票證。如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似以下內容：

[{
  "Success": null,
  "Message": null
}] 

範例 - 還原票證

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

   {
     "id": "20"
   }

這個範例會還原票證。如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似以下內容：

[{
  "Success": "true"
}] 

範例 - 復原遭停權的票證

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

   {
     "id": "18726501985809"
   }

這個範例會復原已暫停的票證。如果動作成功，連接器工作 connectorOutputPayload 回應參數的值會類似以下內容：

[{
  "Id": "60921"
}]

實體作業範例

範例 - 對工單執行清單作業

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

您可以對下列實體執行「列出」作業：

附件、工單留言、工單表單、工單欄位、要求、工單稽核、工單指標、已暫停的工單、共用協議、使用者、使用者身分、使用者相關資訊、使用者欄位、機構欄位和工作狀態

示例 - 取得票券的操作

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Tickets。
3. 選取 Get 作業，然後按一下「完成」。
4. 這裡的 entityId 設為 34.0。如要設定 entityId，請在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 部分，按一下 entityId，然後在 Default Value 欄位中輸入 34.0。

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

工單表單、工單欄位、要求、工單稽核、已暫停的工單、使用者欄位、使用者身分和使用者

範例 - 對 Tickets 建立作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Tickets。
3. 選取 Create 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "Subject": "Zendesk_Create_Ticket",
       "RawSubject": "Zendesk_Create",
       "Description": "this ticket is related to application integration Create operation",
       "Type": "incident",
       "Priority": "urgent",
       "Status": "open",
       "Recipient": null,
       "HasIncidents": false,
       "DueAt": null,
       "RequesterId": 3.84625885158E11,
       "SubmitterId": 3.84625883418E11,
       "AssigneeId": 3.84625883418E11,
       "OrganizationId": "16665992392721",
       "GroupId": 3.60008282358E11,
       "TicketFormId": 3.60001719218E11,
       "BrandId": 3.60003285058E11,
       "Tags": null,
       "ViaChannel": "web",
       "ViaSource": "{\r\n  \"from\": null,\r\n  \"to\": null,\r\n  \"rel\": null\r\n}",
       "CustomFields": null,
       "SatisfactionRating": null,
       "SharingAgreementIds": null,
       "AllowChannelback": false,
       "IsPublic": true,
       "Url": "https://altostrat.zendesk.com/api/v2/tickets/1.json"
     }
     

   如果整合成功，連接器工作的 connectorOutputPayload 欄位會包含類似下列內容的值：

    {
       "Id": 38.0
     }
     

範例 - 對 TicketForms 建立作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 TicketForms。
3. 選取 Create 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "Name": "Altostrat_Zendesk1",
       "RawName": "Altostrat_Zendesk1",
       "DisplayName": "Altostrat_Issues1",
       "RawDisplayName": "Altostrat_Issues1",
       "Position": 2.0,
       "Active": true,
       "EndUserVisible": true,
       "Default": false,
       "InAllBrands": true,
       "RestrictedBrandIds": null,
       "FallbackToDefault": null,
       "AssociatedToBrand": null
     }
     

   如果整合成功，TicketForms 工作的 connectorOutputPayload 回應參數值會類似以下內容：

   {
       "Id":1.8104712053393E13
     }
     

範例 - 對 TicketFields 建立作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 TicketFields。
3. 選取 Create 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "Type": "text",
       "Title": "New field created",
       "RawTitle": null,
       "Description": "Please create the new field",
       "RawDescription": null,
       "Position": 2.0,
       "Active": true,
       "Required": false,
       "CollapsedForAgents": false,
       "RegexpForValidation": null,
       "VisibleInPortal": true,
       "EditableInPortal": true,
       "Tag": null,
       "CreatedAt": "2021-07-06 06:35:19.0",
       "UpdatedAt": "2021-07-06 06:35:19.0",
       "SystemFieldOptions": null,
       "CustomFieldOptions": null,
       "Removable": false
     }
     

   如果整合成功，TicketFields 工作的 connectorOutputPayload 回應參數值會類似以下內容：

   {
       "Id": 1.7139061374865E13
     }
     

範例 - 對 SharingAgreements 建立作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 SharingAgreements。
3. 選取 Create 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "Name": "altostrat.zendesk.com",
       "RemoteSubdomain": "altostrat"
     }
     

   如果整合成功，SharingAgreements 工作的 connectorOutputPayload 回應參數值會類似以下內容：

   {
       "Id": 1.7142672288273E13
     }
     

範例 - 對使用者執行建立作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Users。
3. 選取 Create 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "Email": "cloudysanfrancisco@gmail.com",
       "Name": "Altostrat Team"
     }
     

   如果整合成功，Users 工作的 connectorOutputPayload 回應參數值會類似以下內容：

   {
       "Id": 1.7156912480273E13
     }
     

範例 - 對 UserIdentities 建立作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 UserIdentities。
3. 選取 Create 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "UserId": 3.84637722338E11,
       "Type": "email",
       "Value": "cloudysanfrancisco@gmail.com",
       "Verified": false,
       "Primary": true,
       "DeliverableState": "reserved_example",
       "Url": "https://d3valtostrat1625553311.zendesk.com/api/v2/users/384637722338/identities/368240277818.json"
     }
     

   如果整合成功，UserIdentities 工作的 connectorOutputPayload 回應參數值會類似以下內容：

   {
       "Id": 1.6961185982353E13
     } 
     

範例 - 對 UserFields 執行建立作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 UserFields。
3. 選取 Create 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "Title": "Support description",
       "Type": "text",
       "Key": "support_description"
     }
     

   如果整合成功，UserFields 工作的 connectorOutputPayload 回應參數值會類似以下內容：

   {
       "Id": 1.7157236761873E13
     }
     

範例 - 更新票券作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Tickets。
3. 選取 Update 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "Subject": "Google_Altostrat_Zendesk Update",
       "RawSubject": "Google_Altostrat_Zendesk Update",
       "Description": "this ticket is related to googlecloud application integration update check",
       "RequesterId": 1.6854335860497E13
     }
     

5. 這裡的 entityId 設為 35.0。如要設定 entityId，請點按「entityId」，然後在「Default Value」(預設值) 欄位中輸入 35。

   您也可以將 filterClause 設為 35，而非指定 entityId。

   如果整合成功，連接器工作的 connectorOutputPayload 欄位會包含類似下列內容的值：

   {
         Id": 35.0
     }
     

範例 - 更新 TicketForms 的作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 TicketForms。
3. 選取 Update 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "Name": "Ticketforms Updated",
       "DisplayName": "Altostrat_Issues1",
       "RawDisplayName": "Altostrat_Issues1"
     }
     

5. 這裡的 entityId 設為 1.7137314972689E13。如要設定 entityId，請點選「entityId」，然後在「Default Value」(預設值) 欄位中輸入 1.7137314972689E13。

   您也可以將 filterClause 設為 1.7137314972689E13，而非指定 entityId。

   執行這個範例後，連接器工作 connectorOutputPayload 輸出變數會傳回類似下列內容的回應：

   {
         Id": 1.7137314972689E13
     }
     

範例 - 更新 TicketFields 的作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 TicketFields。
3. 選取 Update 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "Description": "Updated description for testing"
     }
     

5. 在此，entityId 會設為 3.60022990118E11。如要設定 entityId，請點選「entityId」，然後在「Default Value」(預設值) 欄位中輸入 3.60022990118E11。

   您也可以將 filterClause 設為 3.60022990118E11，而非指定 entityId。

   執行這個範例後，連接器工作 connectorOutputPayload 輸出變數會傳回類似下列內容的回應：

   {
         Id": 3.60022990118E11
     }
     

範例 - 更新使用者作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Users。
3. 選取 Update 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "Name": "The Customer update",
       "Last Name": "Alex",
       "First Name": "Charlie"
     }
     

5. 這裡的 entityId 設為 3.84625885158E11。如要設定 entityId，請點選「entityId」，然後在「Default Value」(預設值) 欄位中輸入 3.84625885158E11。

   您也可以將 filterClause 設為 3.84625885158E11，而非指定 entityId。

   執行這個範例後，連接器工作 connectorOutputPayload 輸出變數會傳回類似下列內容的回應：

   {
         Id": 3.84625885158E11
     }
     

範例 - 更新 UserFields 的作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 UserFields。
3. 選取 Update 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "Title": "Support description updated",
       "Type": "text",
       "Key": "support_description"
     }
     

5. 這裡的 entityId 設為 1.7157236761873E13。如要設定 entityId，請點選「entityId」，然後在「Default Value」(預設值) 欄位中輸入 1.7157236761873E13。

   您也可以將 filterClause 設為 1.7157236761873E13，而非指定 entityId。

   執行這個範例後，連接器工作 connectorOutputPayload 輸出變數會傳回類似下列內容的回應：

   {
         Id": 1.7157236761873E13
     }
     

範例 - 更新 UserIdentities 的作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 UserIdentities。
3. 選取 Update 作業，然後按一下「完成」。
4. 在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 區段中，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似下列的值：

   {
       "Verified": true
     }
     

5. 在這個實體中，可以使用篩選子句和複合主鍵執行更新作業，因此不需要 entityId。

除了指定 entityId，您也可以將 filterClause 設為 UserId='384625885158' and Id='368234205078'。

執行這個範例後，連接器工作 connectorOutputPayload 輸出變數會傳回類似下列內容的回應：

{
    "Id": 3.68234205078E11
  }
  

範例 - 刪除票卡作業

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Tickets。
3. 選取 Delete 作業，然後按一下「完成」。
4. 這裡的 entityId 設為 35.0。如要設定 entityId，請在「Connectors」(連結器) 任務的「Task Input」(任務輸入內容) 專區中，點選「entityId」，然後在「Default Value」(預設值) 欄位中輸入 35。

您可以對下列實體執行刪除作業：

票券欄位、已暫停的票券、使用者身分、使用者欄位和使用者

在整合服務中使用 Zendesk 連線

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

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