Sebastian Petrus

Posted on Aug 31 Originally published at apidog.com

Cách kết nối Kho lưu trữ GHE.com với Apidog

Kết nối Apidog với GitHub Enterprise Cloud có lưu trữ dữ liệu tại chỗ

Apidog có thể kết nối với các máy chủ thuê GitHub Enterprise Cloud hỗ trợ lưu trữ dữ liệu tại chỗ trên các miền chuyên dụng *.ghe.com. Sau khi Quản trị viên Tổ chức cấu hình máy chủ thuê và Ứng dụng OAuth, người dùng được cấp quyền có thể kết nối kho lưu trữ để nhập, sao lưu và đồng bộ hóa OpenAPI.

Dùng thử Apidog hôm nay

Tích hợp này chỉ dành cho GitHub Enterprise Cloud SaaS có khả năng lưu trữ dữ liệu tại chỗ. Tích hợp không hỗ trợ GitHub Enterprise Server hoặc các miền GitHub tùy chỉnh.

Điều kiện cần

Bạn cần có:

Tổ chức Apidog Enterprise được bật tính năng tích hợp.
Quyền Quản trị viên Tổ chức trong Apidog.
Máy chủ thuê GitHub Enterprise Cloud hỗ trợ lưu trữ dữ liệu tại chỗ trên miền gốc *.ghe.com, chẳng hạn https://company.ghe.com.
Quyền tạo Ứng dụng OAuth trên máy chủ thuê.
Quyền truy cập vào các tổ chức, kho lưu trữ và nhánh GitHub cần kết nối.
Quyền kết nối Git cấp dự án trong Apidog nếu bạn là người kết nối kho lưu trữ.

Bước 1: Tạo Ứng dụng OAuth trên máy chủ GHE.com

Đăng nhập vào máy chủ thuê GHE.com của tổ chức.
Mở phần cài đặt Ứng dụng OAuth và tạo ứng dụng mới.
Nhập tên ứng dụng dễ nhận biết.
Đặt URL trang chủ thành https://apidog.com.
Đặt URL gọi lại ủy quyền thành https://api.apidog.com/passport/github/callback.
Đăng ký ứng dụng.
Sao chép ID Khách hàng.
Tạo và lưu an toàn Mã bí mật khách hàng.

URL gọi lại phải khớp chính xác với URL Apidog đã cung cấp.

Lưu Mã bí mật khách hàng trong hệ thống quản lý bí mật được phê duyệt. Không đưa mã này vào ảnh chụp màn hình, phiếu yêu cầu hoặc tài liệu chia sẻ.

Bước 2: Cấu hình máy chủ GHE.com trong Apidog

Chỉ Quản trị viên Tổ chức mới có thể cấu hình hoặc xóa tích hợp này.

Mở tổ chức Apidog.
Vào Cài đặt Tổ chức > Tích hợp GitHub.
Tìm GitHub Enterprise Cloud Lưu trữ Dữ liệu tại chỗ và chọn Cấu hình.

Nhập URL máy chủ GHE.com, ví dụ https://company.ghe.com.
Chọn OAuth App làm phương thức xác thực.
Nhập ID Khách hàng và Mã bí mật khách hàng.
Lưu cấu hình.

Cấu hình máy chủ thuê và thông tin xác thực OAuth ở cấp tổ chức.

Sau khi lưu, Apidog hiển thị URL máy chủ đã cấu hình. Mã bí mật khách hàng sẽ không được hiển thị hoặc điền lại.

Khi chỉnh sửa cấu hình, để trống trường Mã bí mật khách hàng sẽ giữ nguyên mã hiện tại. Chỉ nhập giá trị mới khi muốn xoay vòng mã.

Bước 3: Kết nối kho lưu trữ từ dự án Apidog

Sau khi hoàn tất cấu hình cấp tổ chức:

Mở dự án Apidog cần kết nối.
Bắt đầu quy trình Kết nối Git hoặc Nhập Git.
Chọn GitHub Enterprise Cloud.
Tiếp tục đến trang ủy quyền trên máy chủ GHE.com đã cấu hình.
Đăng nhập và ủy quyền Ứng dụng OAuth.
Chọn tổ chức GitHub, kho lưu trữ và nhánh.
Hoàn tất kết nối.

Ủy quyền diễn ra trên máy chủ GHE.com đã cấu hình, không phải trên github.com tiêu chuẩn.

Nếu không thấy tổ chức hoặc kho lưu trữ cần dùng, hãy kiểm tra quyền truy cập GitHub và quyền đã cấp cho Ứng dụng OAuth trước khi thay đổi cài đặt Apidog.

Bước 4: Nhập tệp OpenAPI

Để nhập tệp OpenAPI hoặc Swagger từ kho lưu trữ đã kết nối:

Bắt đầu quy trình nhập trong dự án Apidog.
Chọn OpenAPI/Swagger.
Chọn Kho lưu trữ Git.
Chọn tổ chức GitHub, kho lưu trữ, nhánh và tệp.
Chọn Tiếp tục.
Chọn mô-đun đích hiện có hoặc tạo mô-đun mới.
Hoàn tất quá trình nhập.
Xem lại các endpoint và schema trước khi chấp nhận kết quả.

Chọn kho lưu trữ, nhánh và tệp đặc tả phù hợp với dự án.

Nên sử dụng dự án không phải môi trường production cho lần nhập đầu tiên, đặc biệt khi mô-đun đích đã có định nghĩa API.

Bước 5: Chọn quy trình đồng bộ hóa

Kết nối kho lưu trữ có thể hỗ trợ nhiều quy trình. Hãy chọn một nguồn thông tin đáng tin cậy duy nhất và ghi lại quy ước này cho nhóm.

Quy trình	Sử dụng khi	Hành vi quan trọng
Nhập thủ công	Chỉ cập nhật Apidog khi có yêu cầu	Xem lại từng lần nhập và mô-đun đích
Nhập theo lịch trình	Tệp Git là nguồn chính và Apidog cần tự động làm mới	Chạy qua ứng dụng khách cục bộ hoặc Runner tự lưu trữ theo chế độ đã cấu hình
Sao lưu vào Git	Nội dung Apidog cần được ghi vào tệp trong kho lưu trữ	Cấu hình kho lưu trữ, nhánh và đường dẫn đích; bản sao lưu tự động chạy vào thời điểm thấp điểm được lên lịch ngẫu nhiên trong ban đêm
Chế độ ưu tiên đặc tả	Tệp đặc tả là nguồn duy nhất và nhóm làm việc theo Git	Hiện ở giai đoạn beta; webhook thường yêu cầu quyền quản trị kho lưu trữ

Không cấu hình hai quy trình tự động đối lập trên cùng một tệp nếu chưa có quy tắc giải quyết xung đột rõ ràng.

Thiết lập sao lưu vào Git

Tạo hoặc chọn kết nối Git trong cài đặt dự án.
Mở Tổng quan > Đặc tả API của mô-đun.
Thêm hoặc chọn đặc tả OpenAPI.
Bật Sao lưu vào Kho lưu trữ Git.
Chọn kho lưu trữ, nhánh và đường dẫn tệp đích.
Lưu cấu hình.

Để dùng kho lưu trữ làm nguồn thông tin đáng tin cậy, hãy tham khảo Nhập theo lịch trình hoặc Chế độ ưu tiên đặc tả.

Bước 6: Xác minh tích hợp

Chạy một thử nghiệm nhỏ nhưng đầy đủ:

Xác nhận quy trình ủy quyền mở đúng máy chủ GHE.com.
Xác nhận chỉ các tổ chức và kho lưu trữ mong muốn xuất hiện.
Nhập một tệp OpenAPI đã biết và so sánh với nguồn.
Kiểm tra hướng sao lưu hoặc đồng bộ hóa trên một nhánh dùng một lần.
Xác nhận bảo vệ nhánh và quyền kho lưu trữ hoạt động đúng.
Xem lại nhật ký đồng bộ hóa và lỗi.
Xoay vòng Mã bí mật khách hàng, sau đó xác nhận quy trình cập nhật đã được ghi lại hoạt động đúng.

Nếu sử dụng đồng bộ hóa qua webhook, hãy xác minh trình cài đặt có quyền quản trị kho lưu trữ và sự kiện push mong muốn kích hoạt đồng bộ hóa.

Cập nhật hoặc xóa cài đặt tổ chức

Quản trị viên Tổ chức có thể chỉnh sửa URL máy chủ hoặc ID Khách hàng. Để xoay vòng Mã bí mật khách hàng, hãy nhập giá trị mới.

Để xóa cấu hình cấp tổ chức:

Mở Cài đặt Tổ chức > Tích hợp GitHub.
Tìm tích hợp lưu trữ dữ liệu tại chỗ.
Chọn Xóa cài đặt.

Sau khi xóa, người dùng không thể tạo kết nối GitHub Enterprise Cloud mới cho đến khi tích hợp được cấu hình lại. Các kết nối hiện có có thể cần cấu hình hoặc ủy quyền lại, tùy thuộc trạng thái token và cài đặt tổ chức.

Khắc phục sự cố

Sự cố	Điều cần kiểm tra
Không có tùy chọn tích hợp	Tổ chức đã bật tính năng Enterprise và bạn có quyền Quản trị viên Tổ chức chưa?
OAuth trả về lỗi gọi lại	URL gọi lại có chính xác là `https://api.apidog.com/passport/github/callback` không?
Quy trình ủy quyền mở github.com	URL máy chủ có phải máy chủ thuê gốc `*.ghe.com` mong muốn không?
Không thấy kho lưu trữ	Kiểm tra quyền tổ chức, quyền kho lưu trữ và các giới hạn OAuth của tài khoản GitHub.
Người dùng dự án không thể tạo kết nối	Xác nhận người dùng có quyền kết nối Git cấp dự án.
Nhập hoặc đồng bộ hóa thất bại	Kiểm tra nhánh, đường dẫn tệp, định dạng tệp, quyền kho lưu trữ và nhật ký đồng bộ hóa.

Bảo mật và ranh giới lưu trữ dữ liệu

Chỉ Quản trị viên Tổ chức có thể cấu hình hoặc xóa tích hợp GHE.com.
Mã bí mật khách hàng không được hiển thị sau khi cấu hình.
Quyền dự án vẫn kiểm soát người có thể tạo hoặc cập nhật kết nối Git.
OAuth sử dụng máy chủ thuê GHE.com đã cấu hình.
Quyền OAuth có thể bao gồm quyền đọc tổ chức, kho lưu trữ và nhánh; nhập tệp; ghi bản sao lưu; hoặc quản lý hook kho lưu trữ tùy theo quy trình đồng bộ hóa.

Việc kết nối máy chủ hỗ trợ lưu trữ dữ liệu tại chỗ không tự chứng minh rằng mọi dữ liệu liên quan đến GitHub hoặc Apidog đều nằm trong một khu vực. GitHub có tài liệu riêng về dữ liệu thuộc phạm vi dịch vụ và các trường hợp ngoại lệ. Apidog là dịch vụ độc lập với mô hình lưu trữ và triển khai riêng. Hãy xem tài liệu hiện tại của cả hai nhà cung cấp khi đánh giá khả năng lưu trữ dữ liệu tại chỗ hoặc yêu cầu tuân thủ.

Hướng dẫn quản trị API liên quan

Khung Quản trị API — kết nối quyền sở hữu, kiểm soát, bằng chứng và quyết định vòng đời.
Ánh xạ Nhóm SAML với Microsoft Entra ID — gán quyền truy cập nhóm từ nhà cung cấp danh tính.
Trình quét bí mật — phát hiện thông tin xác thực có thể bị lộ.
Nhật ký kiểm tra — điều tra và xuất hoạt động quản trị.
Cung cấp SCIM — quản lý người dùng trong suốt vòng đời danh tính.
Chính sách Doanh nghiệp — kiểm soát thông tin xác thực, thành viên, phiên SSO và lời mời.
Các nhóm API tự phục vụ — hỗ trợ nhóm tự tạo nhưng vẫn duy trì giám sát quyền sở hữu.
Tích hợp GitHub Enterprise Cloud — kết nối kho lưu trữ GHE.com được hỗ trợ cho quy trình OpenAPI.

DEV Community