Giới thiệu Zendesk API (Phần đầu)

Giới thiệu

Zendesk Support là một customer support platform , nó hỗ trợ hơn 80,000 doanh nghiệp và hơn 300 triệu end user trong 150 nước trên thế giới. Rất nhiều doanh nghiệp sử dụng Zendesk API để tự động hòa và nâng cao khả năng hỗ trợ khách hàng với Zendesk Support.

Core API

• API là một JSON API. XML không được hỗ trợ. Xem rõ hơn tại Làm việc với JSON

• Những endpoint được tài liệu hóa với HTTP method của request và một phần định danh resource Ví dụ:

GET /api/v2/help_center/en-us/articles.json

Tiền tố là Zendesk Support URL. Ví dụ

https://obscura.zendesk.com/api/v2/help_center/en-us/articles.json

{} biểu thị gía trị bạn phải thêm vào. Ví dụ:

GET  /api/v2/users/{id}.json

Những ví dụ này là những Curl statements , bạn có thể chạy những lệnh này trong cửa sổ dòng lệnh (command line) và thử nghiệm các API request khác nhau. Để biết thêm chi tiết Cài đặt và sử dụng Curl. Ở Windows, bạn cần thực hiện một số thay đổi để các ví dụ trong document này hoạt động. Xem thêm Sử dụng Curl trên nền Windows

Security và Authentication

• Đây là một SSL-only API, bất kể việc tài khoản của bạn được cấu hình ra sao. Bạn phải là một verified user để tạo ra những API request . Bạn có thể authorize mà không cần sử dụng email và password tương ứng bằng cách sử dụng email và một API token, hoặc với một OAuth access token.
• Về phía khách hàng, CORS request hỗ trợ nếu request đó được authenticated với OAuth access token. Request đó không được hỗ trợ sử dụng basic authentication (cách sử dụng email và password) hoặc email và Zendesk API token. Xem thêm thông tin về Tạo API request từ browser tại Zendesk API guide .

Basic authentication

Password access phải được enabled tại Zendesk Support Admin Interface. Admin > Channels > API sử dụng authencation format sau với email và password:

{email_address}:{password}

Ví dụ:

curl -u jdoe@example.com:hdtR9Ve6 https://obscura.zendesk.com/api/v2/users.json

Nếu một agent hoặc admin đã enabled two-factor authentication trong profile của họ, họ ssẽ không thể enable sử dụng basic authentication (sử dụng email:password). Lựa chọn khác cho họ là sử dụng OAuthe flow. Xem thêm

API token

Api toke được quản lý tại Zendesk Support Admin Interface. Admin > Channels > API. Ở page này bạn có thể xem, thêm, xóa các tokens. Có thể có hơn một token được active trong cùng một thời điểm. Xóa một token đòng nghĩa với việc deactivate nó một cách vĩnh viễn.

Sử dụng cấu trúc authentication sau với địa chỉ mail và một API token:

{email_address}/token:{api_token}

Ví dụ:

curl -u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv https://obscura.zendesk.com/api/v2/users.json

Nếu authenicating thông qua HTTP, url-encode ký tự gạch chéo trong {email_address}/token thành *%2F%

OAuth access token

Zendesk API hỗ trợ OAuth authorization flows. Xem thêm

OAuth access token cũng được sử dụng ở phía khách hàng. Trong request, một access token được sử dụng như là một authorization header như sau:

Authorization: Bearer {access_token}

Ví du:

curl -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo" https://obscura.zendesk.com/api/v2/users.json

Rate Limits

Đây là một API có rate limited. Nghĩa là tùy thuộc vào loại tài khoản của bạn mà họ đồng ý số lượng request trên một phút (per minute)

Add-On cho tăng khả năng đến 2500 request trên một phút. Nó không đồng nghĩa với việc là tằng thêm 2500 request trên phút vào plan. Nghĩa là bạn đang sử dụng Profesional với 400 request thì việc bạn sử dụng Add-On, nó không tăng lên 2900 request trên phút (tăng thêm 2500) mà nó tăng khả năng lên đến 2500 request trên phút (thêm 2100 request trên phút) và tương tự với Enterprise.

Với mỗi endpoint chúng cũng có rate limit của mình. Ví dụ như chúng ta chỉ thực hiện được 30 request update một comment với cùng một ticket được thực hiện bởi một agent với mỗi 10 phút. Hiểu nôm na là với một agent , thực hiện việc cập nhật một bình luận của một thẻ thì trong 10 phút, thì họ , có thể thực hiện nó 30 lần. Nhiều cái viết tiếng anh một chút nó đọc có vẻ dễ hiểu, dịch hoàn toàn sang tiếng việt nó lại trở lên khó hiểu hơn. Còn agent là gì thì nó là một loại user. Zendesk đưa ra 3 loại user : admin, agent, user. Chúng ta sẽ tìm hiểu rõ hơn ở bài viết về Users Zendesk. Xem chi tiết rate limit của mỗi endpoint

Bắt đầu từ mùng 1 tháng Hai năm 2017, REST API có thể gọi bởi Zendesk apps, kèm thèm đó là rate limit tăng lên 700 request trên 5 phút (tương ứng 140 request trên phút) trên một user. Xem thêm Apps-working with request .

Bạn có thể sử so sánh các hoạt động cả mình trong 24h với Core API và rate limit của bạn. Xem thêm Theo dõi họat động của API so với rate limit

Bạn có thể sử dụng response header sau để xác nhận rate limit và đếm số request trên phút tính đến thời điểm hiện tại của tài khoản của bạn:

X-Rate-Limit: 700
X-Rate-Limit-Remaining: 699

Mặc dù vậy thì gioiws hạn request không chỉ tồn tại ở mỗi trong tài liệu này, một hệ thống phải tồn tài giới hạn limit, vì khii thực hiện được việc tăng đột biến request từ một tài khoản, thì việc tấn công từ chối dịch vụ có thể xảy ra. Có thể đáp ứng đến hàng trăm nghìn request trên phút.

Nếu việc vượt qúa rate limit xảy ra, API sẽ trả lời về mã 429 Too Many Requests. Và bạn cần có thể thực hiện gửi request sau một khoảng thời gian.

Đây là bảng rate limit của một số endpoints