Shopify Flow và GraphQL Admin API

Flow sử dụng Shopify GraphQL Admin API để xây dựng quá trình tự động hóa và tiện ích tích hợp nhằm mở rộng và nâng cao bảng điều khiển quản trị Shopify. Flow sử dụng phiên bản 2026-01 của API để đánh giá điều kiện và biến trong dòng công việc cũng như thực hiện thao tác trong cửa hàng Shopify. Vì Flow truy cập dữ liệu cửa hàng bằng cách gọi API, nên bạn có quyền truy cập vào gần như mọi trường có trong API từ Flow.

Vì Shopify phát hành phiên bản API mới 3 tháng một lần, một số dòng công việc có thể cần cập nhật khi các trường bị thay đổi hoặc ngừng sử dụng.

Sử dụng GraphQL Admin API trong dòng công việc

Hầu hết các thao tác trong Flow đều sử dụng GraphQL Admin API để thực hiện thay đổi đối với cửa hàng Shopify. Ví dụ: thao tác Thêm thẻ đơn hàng sử dụng mutation tagsAdd. Thao tác Gửi yêu cầu Admin API có thể sử dụng hầu hết các mutation, kể cả những mutation chưa có sẵn dưới dạng thao tác trong Flow.

Khi tạo dòng công việc, bạn sẽ thường gặp các tên trường và nội dung mô tả dựa trên cú pháp GraphQL Admin API. Ví dụ: để xác định tổng số lượng có thể bán của một mẫu mã trong dòng công việc, bạn sẽ dùng biến variants_item.inventoryQuantity. Một ví dụ khác, để xác định địa điểm khách hàng đã đăng ký nhận bản tin qua email, bạn sẽ dùng biến emailSubscriptionMethod.

Bạn không cần thành thạo API để tạo dòng công việc bằng ứng dụng Flow, nhưng việc hiểu một chút về tên biến và định nghĩa của chúng có thể giúp xây dựng logic dòng công việc cụ thể theo ý muốn. Ví dụ: biết được sự khác biệt giữa displayName và firstName của khách hàng có thể giúp dòng công việc truy cập đúng dữ liệu tùy theo mục đích sử dụng. Các định nghĩa được cung cấp kèm theo từng biến khi bạn xây dựng dòng công việc và bạn có thể nhấp vào để tìm hiểu thêm về bất kỳ biến hoặc định nghĩa nào.

Dữ liệu cửa hàng và GraphQL Admin API

Dòng công việc sử dụng dữ liệu từ cửa hàng trong các điều kiện và thao tác. Flow truy cập dữ liệu cửa hàng bằng GraphQL Admin API, nghĩa là bạn có quyền truy cập vào gần như toàn bộ trường trong API. Nếu thao tác không có dữ liệu cần thiết do yếu tố kích hoạt hoặc thao tác Lấy dữ liệu cung cấp, thì dòng công việc sẽ không chạy và thông báo lỗi sẽ hiển thị.

Ví dụ: một dòng công việc bắt đầu bằng yếu tố kích hoạt Đã tạo khách hàng và nhập dữ liệu khách hàng vào dòng công việc. Nếu yếu tố kích hoạt đó được tiếp nối bằng thao tác Thêm thẻ đơn hàng – yêu cầu dữ liệu đơn hàng chứ không phải dữ liệu khách hàng – thì dòng công việc sẽ báo lỗi thiếu dữ liệu.

Có thể bạn cần xem trước dữ liệu hoặc xem lại tài liệu API để hiểu nội dung API xuất ra và được sử dụng trong Flow, cũng như để đảm bảo dòng công việc xuất ra dữ liệu đúng như mong đợi.

Đối số trường và GraphQL Admin API

Một số trường GraphQL Admin API yêu cầu các đối số, tức là những tham số bổ sung giúp thu hẹp dữ liệu được trả về. Ví dụ: trường product.inCollection cần đối số id của bộ sưu tập để biết cần kiểm tra bộ sưu tập nào. Nếu không có đối số này, trường sẽ không thể trả về kết quả.

Trong Flow, có thể tạo biến từ các trường này bằng cách cung cấp giá trị đối số bắt buộc để sau đó sử dụng trong dòng công việc. Cũng có thể gán tên tùy chỉnh cho biến để dễ tham chiếu hơn trong các bước tiếp theo, ví dụ: đặt tên product.inCollection(id: "gid://shopify/Collection/123456") thành product.inSummerBestsellers.

Tìm hiểu thêm về cách tạo biến từ trường chứa đối số.

Quá trình tạo biến từ trường siêu dữ liệu đòi hỏi thêm thông tin trong Flow do bạn phải tự xác định không gian tên và khóa của từng trường siêu dữ liệu, do đó các đối số luôn là duy nhất đối với cửa hàng. Tìm hiểu thêm về trường siêu dữ liệu trong Flow.

Phiên bản API

Shopify phát hành phiên bản API mới 3 tháng một lần và Flow sẽ áp dụng các phiên bản mới sớm nhất có thể, nhưng có thể sẽ chậm hơn so với phiên bản mới nhất. Khi có thể, các thay đổi giữa những phiên bản sẽ được tự động giải quyết, tuy nhiên một số thay đổi có thể không hề đơn giản, bao gồm những tình huống sau đây:

• Khi các trường bị xóa nhưng không có trường thay thế, có thể ảnh hưởng đến cách đánh giá điều kiện hoặc Liquid.
• Khi các trường có thể nhận giá trị null, có thể ảnh hưởng đến cách đánh giá điều kiện hoặc Liquid.
• Khi giá trị enum thay đổi hoặc các kiểu union hay interface mới được thêm vào, có thể ảnh hưởng đến Liquid hoặc mã.
• Khi đối số mutation thay đổi, có thể ảnh hưởng đến cấu hình của thao tác Send Admin API request.

Một số dòng công việc có thể cần được cập nhật theo cách thủ công. Trong những trường hợp này, dòng công việc có thể hiển thị lỗi Cần cập nhật (Update required) hoặc API không được hỗ trợ (Unsupported API) và hướng dẫn bạn đến tài liệu API liên quan để thực hiện những thay đổi cần thiết trong trình biên tập dòng công việc. Khi các bản cập nhật này được hoàn tất và lưu lại, dòng công việc sẽ tự động cập nhật để sử dụng phiên bản API mới nhất hiện có trong Flow.

Có thể chọn tạm thời bỏ qua sự cố để thực hiện các thay đổi khẩn cấp đối với dòng công việc gặp lỗi tương thích phiên bản API. Nếu không khắc phục những sự cố này, dòng công việc có thể ngừng chạy hoặc gây ra lỗi khi phiên bản API cũ không còn được Shopify hỗ trợ.