Lần đầu tiên bạn chạy apidog run và nó dừng lại với thông báo “No access token found” (Không tìm thấy mã truy cập), bạn đã gặp phải một phần của quy trình làm việc dòng lệnh mà không ai cảnh báo trước. Các cờ lệnh (flags), ID kịch bản, và trình báo cáo (reporters) đều dễ dàng sao chép từ một tab. Xác thực là bước mà một lệnh được sao chép có thể bị lỗi trên máy của bạn, làm lộ bí mật vào nhật ký, hoặc âm thầm hoạt động trên máy tính xách tay của bạn nhưng lại thất bại trong CI vì những lý do mà thông báo lỗi không giải thích.
Hướng dẫn này là câu trả lời chuyên sâu cho bước đó. CLI của Apidog là một gói npm, apidog-cli, chạy các kịch bản kiểm thử API mà bạn xây dựng trong ứng dụng Apidog trực tiếp từ một terminal. Vì những kịch bản đó nằm trong tài khoản của bạn, CLI phải chứng minh rằng nó được phép lấy và chạy chúng, và nó thực hiện điều đó bằng mã truy cập (access token). Xử lý mã truy cập đúng cách một lần và mọi lần chạy sau đó sẽ chỉ cần một dòng lệnh đơn giản. Nếu làm sai, bạn sẽ phải đối mặt với cùng một lỗi xác thực trong ba môi trường khác nhau.
Chúng ta sẽ đi qua toàn bộ các khía cạnh: tạo mã truy cập, đăng nhập bằng apidog login, kiểm tra bạn đang đăng nhập với tư cách ai bằng apidog whoami, nơi mã truy cập được lưu trữ, cách apidog run quyết định sử dụng mã truy cập nào, và phần mà hầu hết các nhóm thường mắc lỗi, xử lý mã truy cập đó như một bí mật trong CI thay vì dán nó vào tệp cấu hình pipeline. Cơ chế cài đặt nằm trong một hướng dẫn riêng; hướng dẫn này chỉ tập trung vào xác thực. Nếu bạn chưa cài đặt CLI, hãy bắt đầu với hướng dẫn cài đặt Apidog CLI, sau đó quay lại đây.
Tại sao CLI lại cần một mã truy cập?
CLI không tự chứa các bài kiểm thử. Nó truy cập vào dự án Apidog của bạn, tìm một kịch bản theo ID và chạy nó giống như cách ứng dụng máy tính để bàn sẽ làm. Thiết kế đó là lý do nó cần xác thực: kịch bản, các giá trị môi trường, các xác nhận đều nằm ở phía máy chủ trong tài khoản của bạn, vì vậy trình chạy phải tự nhận diện trước khi máy chủ cung cấp bất kỳ thông tin nào trong số đó.
Mã truy cập là cách nó tự nhận diện. Mã truy cập được gắn với tài khoản Apidog của bạn, vì vậy một lần chạy được xác thực bằng mã truy cập của bạn có thể thực hiện những gì bạn có thể làm: đọc dự án của bạn, lấy kịch bản của bạn, thực thi chúng đối với các môi trường bạn đã định nghĩa. Đó cũng là lý do tại sao mã truy cập là một thông tin đăng nhập mà bạn phải bảo vệ. Bất kỳ ai giữ nó đều có thể chạy kịch bản với tư cách là bạn, đối với bất kỳ môi trường nào mà các kịch bản đó nhắm tới. Hãy đối xử với nó như cách bạn đối xử với một mã truy cập cá nhân cho bất kỳ dịch vụ nào khác.
Đây là một loại xác thực khác với xác thực mà các bài kiểm thử của bạn thực hiện. Các kịch bản của bạn có thể gửi mã bearer hoặc khóa API riêng của chúng tới các điểm cuối đang được kiểm thử, và đó là một vấn đề riêng biệt được đề cập trong các phương pháp xác thực API. Mã truy cập của CLI xác thực trình chạy với Apidog. Các thông tin đăng nhập bên trong yêu cầu của bạn xác thực các yêu cầu của bạn với API của bạn. Hãy phân biệt rõ hai điều này, vì chúng nằm ở những nơi khác nhau và thay đổi theo các lịch trình khác nhau.
Bước 1: Tạo mã truy cập
Bạn tạo mã truy cập trong Apidog, không phải từ CLI. Có hai nơi nó xuất hiện, và việc bạn sử dụng cái nào tùy thuộc vào những gì bạn đang làm.
Đối với một mã truy cập được giới hạn trong tài khoản của bạn mà bạn sẽ sử dụng lại trên nhiều kịch bản, hãy mở ứng dụng Apidog hoặc bảng điều khiển web, nhấp vào hình đại diện của bạn và tìm trong cài đặt tài khoản của bạn để đến phần mã truy cập API.
Tạo một mã, sao chép ngay lập tức và lưu trữ ở một nơi an toàn như trình quản lý mật khẩu. Bạn thường không thể nhìn thấy chuỗi đầy đủ một lần nữa sau khi rời khỏi trang, điều này là bình thường đối với thông tin đăng nhập và là lý do để sao chép nó ngay khi nó xuất hiện.
Đối với một mã truy cập gắn liền với một kịch bản cụ thể mà bạn đang tích hợp vào CI, có một cách nhanh hơn. Mở kịch bản kiểm thử, chuyển sang tab CI/CD của nó, chọn tùy chọn dòng lệnh và nhấp để tạo mã truy cập. Apidog xây dựng toàn bộ lệnh apidog run cho bạn với mã truy cập, ID kịch bản và ID môi trường đã được điền sẵn. Lệnh được tạo đó là điểm khởi đầu chính thức, và sao chép nó có nghĩa là bạn không bao giờ phải tự gõ ID. Hướng dẫn hoàn chỉnh về Apidog CLI sẽ hướng dẫn chi tiết về tab CI/CD đó.
Dù bằng cách nào, đầu ra cũng là một chuỗi mã truy cập. Điều bạn làm tiếp theo là lựa chọn giữa hai kiểu xác thực.
Bước 2: Chọn kiểu xác thực của bạn
CLI hỗ trợ hai cách để cung cấp mã truy cập, và chúng phù hợp với các tình huống khác nhau.
Đầu tiên là đăng nhập đã lưu. Bạn chạy apidog login một lần, CLI sẽ lưu mã truy cập vào máy của bạn, và mọi lần chạy apidog run sau đó sẽ tự động đọc nó. Không cần mã truy cập trên bất kỳ dòng lệnh nào sau đó. Đây là điều bạn muốn trên máy tính của nhà phát triển mà bạn sử dụng hàng ngày.
Thứ hai là theo từng lệnh. Bạn truyền --access-token trực tiếp trên lệnh apidog run, thường là từ một biến môi trường. Không có gì được lưu trữ, mã truy cập được cung cấp mới mỗi lần, và nó không để lại dấu vết trên đĩa. Đây là điều bạn muốn trong CI, nơi trình chạy là tạm thời và mã truy cập đến từ một bí mật.
Bạn có thể sẽ sử dụng cả hai, đăng nhập đã lưu cục bộ và theo từng lệnh trong pipeline. Hai phần tiếp theo sẽ đề cập đến từng cách.
Bước 3: Đăng nhập cục bộ bằng apidog login
Trên máy tính của riêng bạn, hãy đăng nhập một lần và quên đi mã truy cập. Biểu mẫu tương tác sẽ nhắc bạn nhập nó để chuỗi không bao giờ xuất hiện trong lịch sử shell của bạn:
apidog login
CLI sẽ hỏi mã truy cập của bạn, bạn dán nó vào và nhấn Enter. Đằng sau hậu trường, nó xác thực mã truy cập với Apidog trước khi lưu bất cứ thứ gì; một mã truy cập không hợp lệ hoặc đã hết hạn sẽ bị từ chối ngay lập tức thay vì gây lỗi sau này trong lần chạy đầu tiên của bạn. Khi thành công, nó xác nhận tài khoản mà nó đã đăng nhập và cho bạn biết nơi nó đã lưu trữ thông tin đăng nhập.
Nếu bạn muốn truyền mã truy cập trực tiếp, ví dụ như trong một tập lệnh cài đặt, hãy sử dụng cờ --with-token:
apidog login --with-token YOUR_ACCESS_TOKEN
Một lưu ý với cách này: mã truy cập trên dòng lệnh sẽ lưu vào lịch sử shell của bạn và có thể bị đọc từ danh sách tiến trình khi lệnh đang chạy. Ưu tiên sử dụng apidog login tương tác cho việc sử dụng trực tiếp, và dành --with-token cho thiết lập không tương tác nơi bạn đọc giá trị từ một biến mà bạn kiểm soát. Không bao giờ đặt mã truy cập thật vào một script mà bạn commit.
Mã truy cập đi đâu? CLI ghi nó vào một tệp cấu hình dưới thư mục .apidog trong thư mục chính của bạn. Đó là một kho lưu trữ thông tin đăng nhập cục bộ trên máy tính của riêng bạn, và đó chính là điểm mấu chốt: mã truy cập nằm trên đĩa nơi chỉ tài khoản người dùng của bạn mới có thể đọc được, và CLI sẽ lấy nó trong mỗi lần chạy sau đó mà bạn không cần phải gõ lại. Nếu bạn đang sử dụng một máy tính dùng chung hoặc dùng một lần, hãy bỏ qua việc đăng nhập đã lưu và thay vào đó sử dụng mã truy cập theo từng lệnh, để không có gì còn lại sau khi bạn rời đi.
Bước 4: Xác minh bằng apidog whoami
Sau khi đăng nhập, hãy xác nhận rằng nó đã hoạt động trước khi bạn phụ thuộc vào nó:
apidog whoami
Điều này in ra tài khoản mà CLI hiện đang xác thực. Đây là cách nhanh nhất để trả lời câu hỏi “tôi đã đăng nhập chưa, và với tư cách là ai?” mà không cần chạy một kịch bản thực tế. Hãy sử dụng nó bất cứ khi nào một lần chạy thất bại với lỗi xác thực và bạn không chắc liệu vấn đề là do mã truy cập hay một yếu tố khác; nếu whoami hiển thị tài khoản của bạn, thì việc đăng nhập đã lưu là ổn và bạn có thể tìm kiếm vấn đề ở nơi khác.
apidog whoami cũng chấp nhận --access-token nếu bạn muốn kiểm tra một mã truy cập cụ thể thay vì mã đã lưu. Điều này tiện lợi để xác nhận một mã truy cập CI hợp lệ trước khi bạn tin tưởng nó trong một pipeline: dán mã truy cập vào lệnh apidog whoami --access-token YOUR_ACCESS_TOKEN một lần từ một terminal an toàn, xem nó liên kết với tài khoản nào, sau đó chuyển nó vào kho bí mật của bạn.
Khi bạn đã hoàn tất trên một máy tính dùng chung, hoặc khi bạn muốn chuyển sang một tài khoản khác, hãy xóa thông tin đăng nhập đã lưu:
apidog logout
Điều đó xóa mã truy cập đã lưu khỏi tệp cấu hình. Lần chạy apidog run tiếp theo sẽ cần đăng nhập mới hoặc cờ --access-token, đây là hành vi bạn muốn sau khi trả lại máy tính.
Bước 5: Cách apidog run chọn mã truy cập
Khi bạn hiểu thứ tự mà trình chạy kiểm tra, lỗi “No access token found” (Không tìm thấy mã truy cập) sẽ không còn là bí ẩn nữa. Khi bạn gọi apidog run, CLI tìm kiếm mã truy cập theo thứ tự này:
- Cờ
--access-tokenđược truyền trên lệnh, nếu có. - Mã truy cập được lưu trữ trên đĩa từ một lần
apidog logintrước đó.
Nếu nó không tìm thấy cả hai, nó sẽ dừng lại và yêu cầu bạn chạy login trước hoặc truyền --access-token. Ưu tiên này rất hữu ích: một cờ lệnh luôn thắng thế so với đăng nhập đã lưu, vì vậy bạn có thể đăng nhập bằng tài khoản của mình hàng ngày và vẫn có thể ghi đè bằng một mã truy cập khác cho một lần chạy đặc biệt mà không cần đăng xuất.
Trong thực tế, điều này có nghĩa là các lần chạy cục bộ của bạn có thể ngắn gọn như các ID:
apidog run -t 605067 -e 1629989 -n 1 -r cli
Không có mã truy cập trên dòng đó, vì đăng nhập đã lưu cung cấp nó. -t đặt tên kịch bản theo ID, -e chọn môi trường, -n 1 chạy một lần và -r cli in ra báo cáo dễ đọc. So sánh với dạng CI, nơi bạn truyền mã truy cập một cách rõ ràng vì không có gì được lưu trữ:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli
Cùng một lệnh, cùng một kịch bản, nguồn xác thực khác nhau. Đó là sự khác biệt hoàn toàn giữa xác thực cục bộ và CI, và phần còn lại của hướng dẫn này là về việc thiết lập đúng phần CI. Để tham khảo đầy đủ các cờ lệnh phía sau các lần chạy này, hướng dẫn hoàn chỉnh về Apidog CLI bao gồm mọi tùy chọn.
Bước 6: Xử lý mã truy cập như một bí mật trong CI
Đây là nơi các nhóm thường gặp rắc rối. Giải pháp là một quy tắc: mã truy cập nằm trong kho bí mật của hệ thống CI của bạn và nó đến lệnh dưới dạng một biến môi trường. Nó không bao giờ xuất hiện trong một tệp đã commit, một định nghĩa pipeline đã được kiểm tra vào kho lưu trữ, hoặc một nhật ký xây dựng.
Không đăng nhập bên trong CI, và không ghi mã truy cập vào một tệp mà trình chạy tạo ra. Sử dụng dạng --access-token theo từng lệnh, được cấp từ một bí mật đã được che giấu. Mọi ví dụ dưới đây đều tuân theo cùng một hình thức, bí mật được đặt tên một lần trong nền tảng, được tham chiếu là $APIDOG_ACCESS_TOKEN trong bước chạy.
GitHub Actions
Lưu mã truy cập trong phần Cài đặt của kho lưu trữ, trong Secrets and variables, sau đó hiển thị nó cho bước thông qua env:
- name: Run API test scenario
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
GitHub tự động che giấu bí mật trong nhật ký, và việc truyền nó qua env giữ nó không xuất hiện trên dòng lệnh hiển thị. Lỗi phổ biến nhất ở đây là không khớp tên: khóa env, tham chiếu ${{ secrets.X }} và bí mật bạn đã tạo trong Cài đặt đều phải sử dụng cùng một tên. Quy trình làm việc hoàn chỉnh, bao gồm các tạo phẩm báo cáo, nằm trong Apidog CLI trong GitHub Actions.
GitLab CI
Lưu APIDOG_ACCESS_TOKEN dưới dạng một biến CI/CD đã được che giấu, bảo vệ trong phần Cài đặt, không bao giờ trong tệp .gitlab-ci.yml. Sau đó tham chiếu trực tiếp nó, vì GitLab tự động đưa các biến dự án vào môi trường công việc:
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli
Đánh dấu biến là “masked” (đã che giấu) cho GitLab biết để ẩn nó khỏi nhật ký công việc; đánh dấu nó là “protected” (đã bảo vệ) giữ nó khỏi các nhánh không được bảo vệ, để một fork hoặc một nhánh tính năng không thể lấy cắp nó.
Jenkins
Lưu mã truy cập dưới dạng thông tin đăng nhập Jenkins, sau đó liên kết nó trong khối environment để nó có sẵn dưới dạng biến mà không bao giờ được in ra:
pipeline {
agent any
environment {
APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
}
stages {
stage('API tests') {
steps {
sh 'apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit,cli'
}
}
}
}
Jenkins che giấu thông tin đăng nhập được liên kết theo cách này trong đầu ra console. Nếu bạn xây dựng toàn bộ pipeline xung quanh bước này, Apidog CLI trong một pipeline CI/CD bao gồm cấu trúc xung quanh.
Mô hình này giống hệt nhau trên mọi trình chạy: một bí mật đã được che giấu trong nền tảng, một biến môi trường trong lệnh, và cờ --access-token đọc từ đó. Đó là nguyên tắc tương tự mà bạn áp dụng cho bất kỳ thông tin đăng nhập nào trong một pipeline, và bạn nên đọc các thực tiễn tốt nhất về quản lý khóa API nếu bạn quản lý nhiều hơn một khóa.
Xoay vòng và thu hồi mã truy cập
Mã truy cập không tồn tại mãi mãi. Hãy xoay vòng chúng theo lịch trình và thu hồi chúng ngay khi có thể bị lộ.
Để xoay vòng, hãy tạo một mã truy cập mới trong Apidog, cập nhật bí mật trong mọi hệ thống CI sử dụng nó, và chạy một pipeline để xác nhận mã mới hoạt động. Sau đó thu hồi mã truy cập cũ từ cùng nơi bạn đã tạo nó. Cục bộ, chạy apidog logout sau đó là apidog login với mã mới. Thứ tự này rất quan trọng: cập nhật CI trước khi bạn thu hồi, nếu không bạn sẽ bị lỗi build giữa hai bước.
Thu hồi ngay lập tức nếu một mã truy cập xuất hiện ở nơi không nên, như nhật ký, ảnh chụp màn hình, commit, hoặc một terminal dùng chung. Thu hồi sẽ vô hiệu hóa mã truy cập ở mọi nơi cùng một lúc, vì vậy bất kỳ pipeline nào vẫn sử dụng giá trị cũ sẽ thất bại rõ ràng, đó là tín hiệu bạn muốn. Một bản build thất bại có thể khôi phục được; một thông tin đăng nhập trực tiếp trong nhật ký công khai thì không. Đối với thói quen rộng hơn, các thực tiễn tốt nhất về xoay vòng khóa API bao gồm tần suất.
Một cạm bẫy tinh vi: việc tạo lại mã truy cập trong Apidog sẽ làm vô hiệu mã truy cập trước đó. Nếu bạn tạo lại và quên cập nhật một bí mật CI, pipeline đó sẽ bắt đầu thất bại với lỗi xác thực mặc dù không có gì trong YAML thay đổi. Khi một bản build trước đây vẫn chạy được bỗng nhiên không thể xác thực và bạn không hề chạm vào tệp workflow, thì mã truy cập đã được tạo lại là điều đầu tiên cần kiểm tra.
Khi xác thực thất bại
Lỗi xác thực thường tập trung vào một vài nguyên nhân. Dưới đây là cách phân biệt chúng.
“No access token found.” (Không tìm thấy mã truy cập). CLI không tìm thấy cờ --access-token cũng như đăng nhập đã lưu. Cục bộ, chạy apidog login. Trong CI, xác nhận rằng bí mật đã được điền và cờ --access-token đang đọc từ đó; một biến môi trường trống cũng tạo ra thông báo tương tự.
“Invalid access token” (Mã truy cập không hợp lệ) hoặc lỗi xác thực giữa chừng. Mã truy cập sai, đã hết hạn hoặc đã bị thu hồi. Chạy apidog whoami để kiểm tra mã đã lưu, hoặc apidog whoami --access-token YOUR_TOKEN để kiểm tra một mã cụ thể. Nếu không có mã nào dẫn đến tài khoản của bạn, hãy tạo một mã mới và đăng nhập lại.
Hoạt động cục bộ, thất bại trong CI. Sự không khớp cổ điển. Máy của bạn có một đăng nhập đã lưu, vì vậy các lần chạy cục bộ thành công; trình chạy CI không có gì được lưu trữ và hoàn toàn phụ thuộc vào bí mật. Xác nhận tên bí mật khớp chính xác giữa cài đặt nền tảng và lệnh, và rằng giá trị đã được lưu mà không có khoảng trắng hoặc dòng mới thừa ở cuối, điều này dễ xảy ra khi dán.
“Access denied” (Truy cập bị từ chối) trên một kịch bản cụ thể. Mã truy cập hợp lệ nhưng tài khoản đứng sau nó không thể truy cập dự án đó. Kiểm tra ID dự án và kịch bản, và xác nhận tài khoản của mã truy cập có quyền truy cập vào dự án đó. Đây là vấn đề ủy quyền (authorization), không phải xác thực (authentication); CLI đã chứng minh nó là ai, máy chủ chỉ không cho phép tài khoản đó chạy kịch bản đó.
Mã truy cập đến lệnh nhưng bản build vẫn làm lộ nó. Nếu bạn từng thấy mã truy cập thô trong nhật ký, bạn đang echo nó ở đâu đó, thường là một dòng debug in ra toàn bộ lệnh hoặc môi trường. Hãy che giấu nó: in độ dài của mã truy cập để xác nhận nó đã được điền, không bao giờ in giá trị của nó. Hầu hết các nền tảng CI tự động ẩn các bí mật đã biết, nhưng một lệnh echo toàn bộ lệnh được viết thủ công có thể phá vỡ điều đó.
Vị trí của xác thực trong quy trình làm việc lớn hơn
Xác thực là cánh cổng nhỏ, một lần mà giúp mọi thứ phía sau có thể thực hiện được. Một khi CLI có thể chứng minh nó là ai, việc chạy một kịch bản Apidog trở thành một lệnh duy nhất, cục bộ trong vòng lặp chỉnh sửa-kiểm thử của bạn, trong CI sau mỗi lần đẩy, và thậm chí bên trong một tác nhân lập trình AI chạy các bài kiểm thử cho bạn. Mô hình cuối cùng đó đáng để xem xét nếu bạn làm việc với các tác nhân: cách sử dụng tác nhân AI để kiểm thử API cho thấy cách một CLI đã đăng nhập cho phép một tác nhân chạy các kịch bản của bạn và đọc kết quả, và máy chủ Apidog MCP kết nối các thông số kỹ thuật của bạn với các tác nhân đó trực tiếp.
Mô hình tư duy rất đơn giản. Đăng nhập một lần trên máy của bạn với apidog login, xác minh bằng apidog whoami, và để mã truy cập đã lưu xử lý mọi lần chạy sau đó. Trong CI, bỏ qua bước đăng nhập, giữ mã truy cập trong một bí mật đã được che giấu và truyền nó theo từng lệnh với --access-token. Xoay vòng theo lịch trình, thu hồi khi nghi ngờ, và cập nhật CI trước khi thu hồi. Đó là toàn bộ câu chuyện về xác thực, và khi đã xử lý xong, CLI sẽ ẩn vào nền, nơi một trình chạy kiểm thử tốt thuộc về.
Bạn tiếp tục soạn thảo các kịch bản một cách trực quan trong Apidog, và CLI sẽ chạy chúng ở bất cứ nơi nào không có người giám sát. Tải Apidog để thiết lập kịch bản đầu tiên của bạn, sau đó hướng trình chạy đến đó. Đối với tất cả những gì trình chạy có thể làm một khi đã được xác thực, hướng dẫn hoàn chỉnh về Apidog CLI là tài liệu tham khảo bạn nên giữ mở.