Cách gọi API bên ngoài từ Workspace Studio

Một quy trình làm việc trong Google Workspace Studio có thể cần dữ liệu từ bên ngoài Gmail, Drive hoặc Chat: trạng thái đơn hàng, số liệu từ cơ sở dữ liệu hoặc phản hồi từ một công cụ nội bộ. Để truy xuất dữ liệu này hoặc gửi thông tin đến một dịch vụ khác, bạn có thể thêm bước này. Gửi webhookThao tác này thực hiện yêu cầu HTTP đến địa chỉ của API mà bạn đã chỉ định.

Bạn không cần phải cấu hình lệnh gọi hàm Gemini để thực hiện yêu cầu đó. Trong Workspace Studio, luồng sẽ thực thi bước webhook và nhận phản hồi. Sau đó, nếu thấy hữu ích, bạn có thể chuyển phản hồi đó đến một bước khác để tóm tắt, trích xuất dữ liệu hoặc truyền đạt kết quả.

Những thứ bạn cần trước khi kết nối với API.

Bước đầu tiên là xác minh xem tổ chức của bạn có thể sử dụng webhook hay không. Chức năng này nằm ở... bản xem trước giới hạn và bị vô hiệu hóa theo mặc định. Quản trị viên phải đăng nhập. Ứng dụng > Google Workspace > Workspace Studio > Cài đặt Webhook và kích hoạt nó cho đơn vị tổ chức tương ứng.

Trong một số phiên bản, người quản trị cũng có thể giới hạn số kết nối chỉ còn một. danh sách các tên miền và URL được cho phépNếu bước này xuất hiện trong Studio nhưng không thể kết nối với API của bạn, hãy xác minh rằng địa chỉ đích đã được ủy quyền. Ngoài ra, theo mặc định, các thao tác liên quan đến webhook yêu cầu người dùng xem xét và xác nhận bước này trước khi thực hiện.

Từ dịch vụ bên ngoài, bạn cần biết URL của nó, các phương thức HTTP mà nó hỗ trợ và định dạng dữ liệu mà nó mong đợi. Ngoài ra, hãy kiểm tra cách thức xác thực của nó: một API công khai chỉ đọc có các yêu cầu khác với một API riêng tư yêu cầu mã thông báo hoặc tiêu đề đặc biệt.

Hướng dẫn cách gọi API từ Workspace Studio từng bước một

Đi vào studio.workspace.google.com và tạo một quy trình làm việc với trình kích hoạt bạn cần. Ví dụ, bạn có thể bắt đầu quy trình khi nhận được một email đáp ứng các điều kiện nhất định. Sau đó, hãy làm theo các bước sau:

1. Nhấn Thêm bước và chọn Gửi webhook.
2. Nhập vào URL đầy đủ của API, bao gồm cả tiền tố https://Địa chỉ phải cố định: trường này không hỗ trợ các biến luồng.
3. Chọn phương thức HTTP. LẤY Nó được dùng để truy vấn dữ liệu; BƯU KIỆNđể gửi chúng hoặc tạo bản ghi. Chúng cũng có sẵn PUT, PATCH và DELETE.
4. Nếu API yêu cầu phần thân yêu cầu, hãy viết nó vào trường nội dung hoặc tải trọngGoogle khuyến nghị sử dụng JSON khi dịch vụ nhận dữ liệu yêu cầu định dạng này.
5. Tạo một thực thi kiểm thửKiểm tra kết quả và kích hoạt quy trình sau khi bạn đã xác nhận rằng nó hoạt động.

Hãy nhớ rằng bài kiểm tra thực hiện hành độngNếu bạn cấu hình phương thức POST để tạo bản ghi hoặc DELETE để xóa bản ghi, trước tiên hãy sử dụng môi trường thử nghiệm hoặc dữ liệu mà bạn có thể chỉnh sửa mà không gặp sự cố.

Ví dụ: gửi thông báo đến một công cụ bên ngoài

Hãy tưởng tượng nhóm của bạn có một API tạo ra các cảnh báo trong... https://api.ejemplo.com/v1/avisosĐịa chỉ này là minh họaBạn cần thay thế nó bằng mã từ dịch vụ của mình. Nếu tài liệu của dịch vụ đó cho biết nó chấp nhận phương thức POST và phần thân JSON, bạn có thể cấu hình bước đó với nội dung như sau: {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

Bạn cũng có thể chèn một biến lưu lượng Ví dụ, trong phần nội dung, bạn có thể bao gồm chủ đề của email đã kích hoạt nó. Hãy thực hiện điều này từ bộ chọn biến của Studio và kiểm tra kết quả: nếu văn bản được chèn chứa dấu ngoặc kép hoặc các ký tự đặc biệt khác, nó có thể làm hỏng JSON. Biến có thể được sử dụng trong nội dung, nhưng không có trong trường URL.

Nếu bạn cần truy xuất dữ liệu, hãy chọn GET và nhập URL cố định đã chứa các tham số cần thiết. Workspace Studio sẽ bỏ qua bất kỳ nội dung nào bạn đã viết trong phần thân của yêu cầu GET.

Nên làm gì với phản hồi từ API?

Bước webhook để lại phản hồi dịch vụ dưới dạng văn bản Lưu trữ dữ liệu vào một biến có sẵn cho các bước tiếp theo. Bạn có thể sử dụng biến này để gửi thông báo, viết tóm tắt hoặc yêu cầu bước xử lý dữ liệu bằng AI trích xuất dữ liệu cụ thể.

Ví dụ, nếu API trả về trạng thái của một đơn hàng, bước tiếp theo có thể truyền đạt trạng thái đó cho nhóm. Hãy chọn rõ ràng biến chứa phản hồi: các bước tiếp theo không tự động nhận được tất cả những gì đã xảy ra trước đó trong quy trình. Nên kiểm tra nội dung trả về trước khi viết các hướng dẫn phụ thuộc vào nó.

Nếu API yêu cầu xác thực hoặc logic phức tạp hơn.

Cấu hình cơ bản được ghi lại cho Gửi webhook Nó bao gồm URL, phương thức và phần thân tùy chọn. Nếu quá trình tích hợp của bạn cần lấy mã thông báo OAuth, xây dựng URL với các tham số biến đổi, thêm các tiêu đề cụ thể hoặc chuyển đổi phản hồi trước khi tiếp tục, hãy kiểm tra xem bước này có đáp ứng các yêu cầu đó hay không.

Nếu phương án đó không hiệu quả, một lựa chọn khác là phát triển một giải pháp khác. Bước tùy chỉnh cho Workspace Studio thông qua một plugin. Trong triển khai Google Apps Script, dịch vụ UrlFetchApp Giải pháp này cho phép bạn gửi yêu cầu đến các API bên ngoài và xử lý phản hồi JSON. Tuy nhiên, giải pháp này yêu cầu phát triển và cấu hình quyền phù hợp; nó không cần thiết đối với các yêu cầu đơn giản mà bước xử lý gốc đã có thể thực hiện được.

Tránh dán khóa riêng tư vào các trường hiển thị của quy trình hoặc nhúng chúng vào URL được chia sẻ. Trước khi gửi dữ liệu từ Gmail, Chat hoặc Lịch, hãy xác minh thông tin mà dịch vụ bên ngoài sẽ nhận được và liệu dịch vụ đó có được phép xử lý thông tin đó hay không.

Cách xác định lỗi trong webhook

Nếu kết nối thất bại, hãy mở tab Hoạt động của luồng xử lý. Tại đó, bạn có thể xem toàn bộ lỗi và phản hồi được gửi bởi máy chủ đích. Thông tin này giúp phân biệt giữa sự cố cấu hình Studio và yêu cầu bị API từ chối.

• Bước này không hiển thị: Hãy kiểm tra với quản trị viên của bạn xem webhook có được bật cho đơn vị tổ chức của bạn hay không.
• URL đã bị chặn: Hãy kiểm tra danh sách các địa chỉ được phép, nếu phiên bản của bạn có quy định hạn chế đó.
• Lỗi 400: Kiểm tra định dạng nội dung và các trường bắt buộc mà API yêu cầu.
• Lỗi 401 hoặc 403: Xem xét lại các quyền hạn và phương thức xác thực mà dịch vụ yêu cầu.
• Lỗi 429: Kiểm tra xem bạn đã vượt quá giới hạn yêu cầu đối với API mục tiêu chưa.
• Lỗi 500: Kiểm tra trạng thái và hồ sơ của dịch vụ nhận yêu cầu.

Cũng cần lưu ý những hạn chế chung của Workspace Studio: hiện tại nó hỗ trợ tối đa... 25 luồng dữ liệu mỗi người dùng y 20 bước cho mỗi quy trìnhNgoài ra, còn có giới hạn thực thi kết hợp được đặt lại sau mỗi 24 giờ. Nếu nhiều luồng dừng hoạt động, hãy xem xét hoạt động của chúng trước khi quy kết lỗi cho API.

Đối với hầu hết các kết nối HTTP đơn giản, quy trình khá dễ dàng: bật webhook, cấu hình URL cố định và phương thức chính xác, kiểm tra yêu cầu và sử dụng phản hồi trong các bước tiếp theo. Nếu việc tích hợp yêu cầu xác thực nâng cao hoặc chuyển đổi dữ liệu thông qua mã lập trình, thì việc chuẩn bị một bước tùy chỉnh là hợp lý.