Phần 3: Các API với Lark Base và cách sử dụng trong Chatbot

Trong phần 1 và phần 2, mình đã hướng dẫn cách tạo ứng dụng, thêm sopces và add Ứng dụng vào file Lark Base để lấy quyền edit, bài viết này mình sẽ tổng hợp các API sử dụng với Lark Base

---

Trước tiên, các bạn cần nắm được định nghĩa về:
- app_token
- table_id
- record_id



Mỗi file Lark Base được hiểu là một app, app_token chính là token của file Lark Base. Trong file Lark Base lại chứa nhiều table, mỗi table sẽ có một table_id khác nhau, trong mỗi table lại có các bản ghi (record), mỗi bản ghi là một dòng và sẽ có một record_id để phân biệt

Bạn có thể lấy app_token và table_id tại URL của Lark Base


https://smax-app.sg.larksuite.com/base/UYWnb46XcahdPis2ff1lrMQUgbc?chunked=false&table=tblmEH3OcpviooRV&view=vewr5FtjWZ

Trong ví dụ này, UYWnb46XcahdPis2ff1lrMQUgbc chính là app_token và tblmEH3OcpviooRV là table_id

Để lấy được record_id, bạn cần tạo một cột mới trong table và chọn Field type là Formula


Sau đó bạn chọn Formula editor và nhập record id như hình bên dưới



Sau khi đã nắm rõ được các định nghĩa phía trên, mình sẽ tổng hợp lại một số API mà bạn có thể sử dụng trong Chatbot để thao tác với Lark Base

Giả sử mình có một file Lark Base có các cột như hình phía dưới, bao gồm:
- Facebook: là tên facebook của khách hàng
- page.name: tên page
- page.id: id của page
- id: id của khách hàng
- gender: giới tính của khách hàng


Và mình cũng đã thêm ứng dụng vào làm quyền edit trên file


Mình sẽ bắt đầu với API Create Record (Tạo một bản ghi mới)
Bước 1: Bạn tạo một block Đặt tên là Create Record và thêm một thẻ Json API
Thông số của thẻ Json API sẽ như sau:
- Phương thức: POST
- URL: https://open.larksuite.com/open-apis/auth/v3/app_access_token/internal
- BODY: JSON

{
"app_id":"cli_a5243e3dbc38d010",
"app_secret":"ZfleDIMmqdjwe4PmlRNVccNqKTuVUByB"
}

Bạn lưu ý nhớ thay đúng app_id và app_secret của ứng dụng mình vào nhé, sau đó bạn chọn RESPONSE MAPPING để lưu giá trị app_access_token vào attribute {{app_access_token}}
Ghi nhớ: Bạn phải sử dụng thẻ Json API để lấy token trước tất cả các API nhé, mình chỉ làm mẫu cho API này thôi, các API sau mình sẽ bỏ qua bước này nên mọi người nhớ chú ý


Sau khi có giá trị app_access_token, bạn sẽ đặt thêm 1 thẻ Json API nữa phía dưới thẻ này
Thông số của thẻ Json API thứ 2 này sẽ như sau:
- Phương thức: POST
- URL: https://open.larksuite.com/open-apis/bitable/v1/apps/{{app_id}}/tables/{{table_id}}/records (thay app_id và table_id bằng giá trị trên Lark Base của bạn nhé)
- HEADER: Authorization Bearer {{app_access_token}} ({{app_access_token}} đã được lưu từ bước 1 nên Bot sẽ tự thay giá trị vào nhé)
- BODY: JSON

{
  "fields": {
    "Facebook": "{{full name}}",
    "page.name": "{{page.name}}",
    "page.id": {{page.id}},
    "id": "{{id}}",
    "gender": "{{gender}}"
}
}

với Facebook, page.name, page.id, id và gender là tên các cột trên file Lark Base, còn {{full name}}, {{page.name}}, {{page.id}}, {{id}} và {{gender}} là giá trị của các attribute tương ứng


Sau đó, bạn có thể bấm test block để kiểm tra xem file Lark Base đã được tạo ra dòng mới hay chưa

 
Tiếp theo sẽ là API chỉnh sửa một bản ghi. Ví dụ trong bản ghi mình vừa tạo có record id là recu2aCctBzM7E, mình sẽ chỉnh sửa cột gender từ female thành male
Các bạn vẫn thực hiện các bước như tạo block, tạo thẻ Json để lấy token. Tại thẻ Json thứ 2 các bạn sẽ cài đặt thông số như sau
- Phương thức: PUT
- URL: https://open.larksuite.com/open-apis/bitable/v1/apps/{{app_id}}/tables/{{table_id}}/records/{{record_id}} ({{record_id}} là giá trị của record bạn muốn chỉnh sửa, trong ví dụ trên là recu2aCctBzM7E nhé)
- HEADER: Authorization Bearer {{app_access_token}} ({{app_access_token}} đã được lưu từ bước 1 nên Bot sẽ tự thay giá trị vào nhé)
- BODY: JSON

{
  "fields": {
    "gender": "male"
}
}

Mình sẽ chọn cột chỉnh sửa là cột gender, và giá trị mình muốn chỉnh sửa là thành male


Tiếp theo là API để xóa một record, bạn vẫn cần phải có giá trị của record muốn xóa, sau đó setup thẻ Json với thông số như sau:
- Phương thức: DELETE
- URL: https://open.larksuite.com/open-apis/bitable/v1/apps/{{app_id}}/tables/{{table_id}}/records/{{record_id}} ({{record_id}} là giá trị của record bạn muốn chỉnh xóa, trong ví dụ trên là recu2aCctBzM7E nhé)
- HEADER: Authorization Bearer {{app_access_token}} ({{app_access_token}} đã được lưu từ bước 1 nên Bot sẽ tự thay giá trị vào nhé)


Cuối cùng là lấy chi tiết một bản ghi, các thông số bạn vẫn setup như với xóa một bản ghi nhưng phương thức sẽ thay đổi thành GET nhé
- Phương thức: GET
- URL: https://open.larksuite.com/open-apis/bitable/v1/apps/{{app_id}}/tables/{{table_id}}/records/{{record_id}} ({{record_id}} là giá trị của record bạn muốn lấy giá trị, trong ví dụ trên là recu2aCctBzM7E nhé)
- HEADER: Authorization Bearer {{app_access_token}} ({{app_access_token}} đã được lưu từ bước 1 nên Bot sẽ tự thay giá trị vào nhé)