Chuyển tới nội dung
Sursa Developers

POST/v1/users/import

Nhập người dùng từ CSV

users_import

Gửi tệp CSV trong trường csv. Dòng đầu tiên là dòng tiêu đề. Dấu phân tách là , hoặc ; và được nhận diện từ dòng tiêu đề. Mã hóa là UTF-8 (cho phép BOM), tối đa 1.000 dòng dữ liệu.
Các cột: email (bắt buộc; bí danh e-mail, mail, почта), name (display_name, имя), role (admin, editor, verifier, viewer; bí danh роль), groups (группы; phân tách nhiều nhóm bằng | hoặc ;, theo khóa hoặc theo tên của nhóm thông thường), profile (data_profile, профиль; khóa của hồ sơ dữ liệu). Các cột không xác định được bỏ qua và liệt kê trong ignored_columns.

Với dry_run: true (mặc định), trả về bản xem trước mà không thay đổi gì: hành động và các lỗi của từng dòng. Nếu không, các dòng không có lỗi được thực hiện:
- invite: gửi lời mời với vai trò, hồ sơ và tên từ tệp. Email được gửi nếu đã cấu hình thư, và liên kết được trả về trong phản hồi.
- exists: người dùng có email này đã tồn tại. Người dùng được thêm vào các nhóm từ tệp; vai trò và hồ sơ không thay đổi.
- pending: một lời mời tới địa chỉ này đang chờ được chấp nhận. Các nhóm từ tệp được thêm vào lời mời đó.

Các dòng có lỗi được bỏ qua. Người dùng được mời tham gia các nhóm của họ khi chấp nhận lời mời. create_groups tạo các nhóm thông thường còn thiếu; nếu không có tham số này, nhóm không xác định là lỗi của dòng. Giới hạn người dùng của gói và số chỗ của gói đăng ký được kiểm tra cho tất cả lời mời mới cùng lúc: nếu không đủ, không có gì được thực hiện (402). Giới hạn đối với lời mời thủ công (50 lời mời đang chờ) không áp dụng cho việc nhập. Cần quyền ORG_MANAGE_USERS. Ghi sự kiện users.import vào nhật ký kiểm toán, và invitation.create cho mỗi lời mời.

Xác thực

Gửi khóa API trong header Authorization: Authorization: Bearer <khóa>.

Tham số header

  • Idempotency-Keystring

    Khóa để thử lại an toàn một thao tác ghi: 1 đến 255 ký tự ASCII in được; nên dùng một UUID v4 cho mỗi thao tác logic. Lần thử lại với cùng khóa trong vòng 24 giờ không chạy lại thao tác: dịch vụ trả về phản hồi đã lưu (trạng thái, header và phần thân) kèm header Idempotency-Replayed: true. Cùng khóa nhưng khác phương thức, đường dẫn, Content-Type hoặc phần thân trả về 409 api.idempotency_mismatch; khi yêu cầu đầu tiên vẫn đang chạy, trả về 409 api.idempotency_in_progress kèm Retry-After: 1. Sau phản hồi 5xx hoặc 429, khóa được giải phóng và lần thử lại sẽ chạy lại thao tác. Khóa có phạm vi theo tổ chức và bên gọi (khóa API, người dùng hoặc khóa nguồn tùy chỉnh).

    length ≥ 1, length ≤ 255

Phần thân yêu cầu

application/json

Đối tượng: UsersImportRequest

  • csvstringbắt buộc

    Nội dung tệp CSV ở dạng UTF-8.

    length ≥ 1, length ≤ 2000000

  • dry_runboolean

    Chỉ xem trước (mặc định). false thực hiện các dòng không có lỗi.

    Mặc định: true

  • default_rolestring

    Vai trò cho các dòng không có cột role hoặc có ô trống.

    Mặc định: "viewer"

  • default_profilestring | null

    Hồ sơ dữ liệu cho các dòng không có hồ sơ. Nếu trống, hồ sơ mặc định của tổ chức được dùng (quản trị viên có toàn quyền truy cập).

  • create_groupsboolean

    Tạo các nhóm thường còn thiếu. Khi không có cờ này, nhóm không xác định là lỗi của dòng.

    Mặc định: false

  • ttl_daysinteger

    Thời hạn hiệu lực của lời mời, tính bằng ngày.

    Mặc định: 7≥ 1, ≤ 30

Phản hồi

200Bản xem trước hoặc kết quả nhập, theo từng dòng

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

  • Idempotency-Replayed

    true nghĩa là phản hồi được phát lại từ phản hồi đã lưu cho Idempotency-Key này: thao tác không chạy lại.

application/json

Đối tượng: UsersImportResult

  • dry_runbooleanbắt buộc
  • totalintegerbắt buộc

    Số dòng dữ liệu trong tệp.

  • countsUsersImportCountsbắt buộc
  • delimiterstringbắt buộc

    Ký tự phân tách được phát hiện từ dòng tiêu đề.

  • columnsarray of stringbắt buộc

    Các cột được nhận dạng ở dạng chuẩn (email, name, role, groups, profile).

  • ignored_columnsarray of stringbắt buộc
  • created_groupsarray of stringbắt buộc

    Các nhóm đã được tạo trong lúc thực hiện.

  • limitUsersImportLimitbắt buộc
  • rowsarray of UsersImportRowbắt buộc
400Yêu cầu không hợp lệ: giá trị tham số hoặc trạng thái của đối tượng không cho phép thực hiện hành động (`detail` là thông báo).

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

401Không có thông tin xác thực nào được gửi (không có cookie phiên lẫn khóa API), hoặc không tìm thấy khóa.

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

402Tổ chức đã đạt giới hạn của gói (thẻ, dung lượng lưu trữ hoặc người dùng). `error.details` chứa `kind`, `limit` và `used`.

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

403Hành động không được phép: vai trò không đủ quyền, không có quyền truy cập vào bộ sưu tập hoặc thẻ, yêu cầu chạy ở chế độ “View as”, hoặc tổ chức bị tạm ngưng hay đã bị xóa (`detail` là đối tượng có `code: org_suspended | org_deleted`).

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

413Phần thân yêu cầu vượt quá kích thước cho phép.

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

422Lỗi dữ liệu không hợp lệ: phần thân hoặc tham số không khớp với lược đồ (`detail` là danh sách lỗi dữ liệu không hợp lệ), hoặc giá trị tham số nằm ngoài phạm vi cho phép (`detail` là thông báo).

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

429Quá nhiều yêu cầu (`api.rate_limited`), hạn mức của tổ chức theo phút, ngày hoặc tháng đã dùng hết (`api.quota_exceeded`; `error.details` chứa `quota`, `limit` và `reset_at`), tổ chức đã đạt giới hạn, hoặc dịch vụ trả lời đang bận (`answers.engine_busy`). Hãy chờ khoảng thời gian ghi trong header `Retry-After`.

Header phản hồi

  • Retry-After

    Số giây cần chờ trước khi thử lại yêu cầu.

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

Mã lỗi

Các mã endpoint này có thể trả về trong error.code, ngoài các mã chung của mọi yêu cầu.

Thử lại an toàn

Gửi header Idempotency-Key (ví dụ một UUID) với mỗi yêu cầu POST và PATCH. Một lần thử lại với cùng khóa trong vòng 24 giờ trả về phản hồi đã lưu thay vì thực hiện lại yêu cầu.

Giới hạn tốc độ

Phản hồi có các header RateLimit và RateLimit-Policy cùng các header cũ hơn X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Phản hồi 429 có Retry-After tính bằng giây: hãy chờ rồi thử lại.

← users · Tài liệu tham chiếu API