Apidog có thể kết nối với các máy chủ thuê GitHub Enterprise Cloud có khả năng lưu trữ dữ liệu tại chỗ được lưu trữ trên các tên miền `*.ghe.com` chuyên dụng. 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 dự án được ủy quyền có thể kết nối các kho lưu trữ và sử dụng các quy trình làm việc nhập, sao lưu và đồng bộ hóa OpenAPI được hỗ trợ.
Tích hợp này dành cho các máy chủ thuê SaaS GitHub Enterprise Cloud có khả năng lưu trữ dữ liệu tại chỗ. Nó không hỗ trợ GitHub Enterprise Server hoặc bất kỳ tên miền GitHub tùy chỉnh nào.
Trước khi bạn bắt đầu
Bạn cần:
- một tổ chức Apidog Enterprise có quyền truy cập vào tính năng tích hợp
- quyền Quản trị viên Tổ chức trong Apidog
- một máy chủ thuê GitHub Enterprise Cloud có khả năng lưu trữ dữ liệu tại chỗ trên một tên miền gốc `*.ghe.com`, ví dụ như `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 mà bạn định kết nối
Người dùng kết nối kho lưu trữ cũng phải có quyền kết nối Git cấp dự án có liên quan trong Apidog.
Bước 1: Tạo Ứng dụng OAuth trên máy chủ thuê GHE.com
- Đăng nhập vào máy chủ thuê GHE.com của tổ chức bạn.
- Mở cài đặt Ứng dụng OAuth.
- Tạo Ứng dụng OAuth 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 OAuth.
- Sao chép ID Khách hàng.
- Tạo và sao chép 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 đã được tài liệu hóa.
Lưu Mã bí mật khách hàng vào hệ thống quản lý bí mật đã được phê duyệt của bạn. Không đặt nó trong ảnh chụp màn hình, phiếu yêu cầu hoặc tài liệu được chia sẻ.
Bước 2: Cấu hình máy chủ thuê 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ính năng tích hợp này.
- Mở tổ chức Apidog.
- Truy cập Cài đặt Tổ chức.
- Mở 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 pháp xác thực.
- Nhập ID Khách hàng của Ứng dụng OAuth.
- Nhập Mã bí mật khách hàng của Ứng dụng OAuth.
- Lưu cấu hình.
Cấu hình máy chủ thuê và thông tin xác thực Ứng dụng 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 không được hiển thị hoặc điền trước lại.
Khi chỉnh sửa cấu hình sau này, việc để trống trường Mã bí mật khách hàng sẽ giữ nguyên mã bí mật hiện có. Chỉ nhập giá trị mới khi bạn muốn xoay vòng nó.
Bước 3: Kết nối kho lưu trữ từ một dự án Apidog
Sau khi cấu hình cấp độ tổ chức hoàn tất:
- mở dự án Apidog yêu cầu;
- bắt đầu quy trình làm việc 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ủ thuê GHE.com đã cấu hình;
- đăng nhập và ủy quyền Ứng dụng OAuth;
- chọn tổ chức GitHub;
- chọn kho lưu trữ và nhánh;
- hoàn tất kết nối.
Ủy quyền được thực hiện trên máy chủ thuê GHE.com đã cấu hình, không phải trên github.com tiêu chuẩn.
Nếu thiếu tổ chức hoặc kho lưu trữ mong muốn, hãy kiểm tra quyền truy cập của tài khoản GitHub và ủy quyền Ứng dụng OAuth trước khi thay đổi cài đặt tổ chức 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ột mô-đun mới;
- hoàn tất việc nhập;
- xem lại các điểm cuối và lược đồ đã nhập trước khi chấp nhận kết quả.
Chọn kho lưu trữ, nhánh và tệp đặc tả theo yêu cầu của dự án.
Sử dụng một dự án không sản xuất cho lần nhập đầu tiên, đặc biệt khi mô-đun đích đã chứa các định nghĩa API.
Bước 5: Chọn quy trình làm việc đồng bộ hóa liên tục
Kết nối kho lưu trữ có thể hỗ trợ các quy trình làm việc khác nhau. Chọn một nguồn thông tin đáng tin cậy duy nhất và tài liệu hóa nó cho nhóm.
| Quy trình làm việc | Sử dụng khi | Hành vi quan trọng |
|---|---|---|
| Nhập thủ công | Các thay đổi chỉ được đưa vào 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 vẫn là nguồn và Apidog nên làm mới nó theo một khoảng thời gian nhất định | Chạy thông qua ứng dụng khách cục bộ hoặc Runner tự lưu trữ theo chế độ thực thi đã cấu hình |
| Sao lưu vào Git | Nội dung Apidog phải được ghi vào một tệp kho lưu trữ | Cấu hình kho lưu trữ, nhánh và đường dẫn tệp đích; các bản sao lưu tự động chạy trong khoảng thời gian thấp điểm ngẫu nhiên được lên lịch vào ban đêm |
| Chế độ ưu tiên đặc tả | Tệp đặc tả là nguồn thông tin đáng tin cậy duy nhất và nhóm chỉnh sửa thông qua quy trình làm việc hướng Git | Chế độ này hiện đang trong giai đoạn thử nghiệm beta; cài đặt 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 làm việc tự động đối lập trên cùng một tệp mà không có quy tắc giải quyết xung đột rõ ràng.
Để sao lưu:
- 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 kết nối kho lưu trữ, nhánh và đường dẫn tệp đích;
- lưu cấu hình.
Để có một nguồn thông tin đáng tin cậy được điều khiển bởi kho lưu trữ, hãy sử dụng Nhập theo lịch trình hoặc xem lại Chế độ ưu tiên đặc tả.
Bước 6: Xác minh tích hợp
Chạy một thử nghiệm toàn diện nhỏ:
- xác nhận ủy quyền mở máy chủ thuê GHE.com đã cấu hình
- xác nhận chỉ các tổ chức và kho lưu trữ mong muốn là có sẵn
- nhập một tệp OpenAPI đã biết và so sánh kết quả với nguồn
- kiểm tra hướng sao lưu hoặc đồng bộ hóa đã chọn trong 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 như mong đợi
- xem lại nhật ký đồng bộ hóa hoặc lỗi
- xoay vòng Mã bí mật khách hàng của Ứng dụng OAuth và xác nhận quy trình cập nhật được tài liệu hóa hoạt động
Nếu sử dụng đồng bộ hóa webhook, hãy xác minh rằng trình cài đặt có quyền quản trị kho lưu trữ và sự kiện đẩy 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 và có thể xoay vòng Mã bí mật khách hàng bằng cách nhập một giá trị mới.
Để xóa cấu hình cấp độ tổ chức, hãy mở Cài đặt Tổ chức > Tích hợp GitHub, tìm tính năng tích hợp lưu trữ dữ liệu tại chỗ và chọn Xóa cài đặt.
Sau khi cài đặt bị xóa, người dùng không thể tạo kết nối GitHub Enterprise Cloud mới cho đến khi tính năng tích hợp được cấu hình lại. Các kết nối hiện có có thể yêu cầu cấu hình lại hoặc ủy quyền lại tùy thuộc vào trạng thái mã thông báo và cài đặt tổ chức.
Khắc phục sự cố
| Sự cố | Những điều cần kiểm tra |
|---|---|
| Tùy chọn tích hợp không khả dụng | Xác nhận tổ chức có quyền truy cập vào tính năng Enterprise và bạn là Quản trị viên Tổ chức. |
| OAuth trả về lỗi gọi lại | Xác nhận URL gọi lại của Ứng dụng OAuth chính xác là https://api.apidog.com/passport/github/callback. |
| Ủy quyền mở github.com | Xác nhận máy chủ cấp tổ chức là máy chủ thuê gốc *.ghe.com mong muốn. |
| Thiếu kho lưu trữ | Kiểm tra quyền truy cập tổ chức và kho lưu trữ của người dùng GitHub được ủy quyền và mọi hạn chế OAuth. |
| 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 yêu cầu. |
| Nhập hoặc đồng bộ hóa thất bại | Kiểm tra nhánh đã chọn, đườ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 tại chỗ
- Chỉ Quản trị viên Tổ chức mới có thể cấu hình hoặc xóa tính năng 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 ai có thể tạo hoặc cập nhật kết nối Git.
- Ủy quyền OAuth diễn ra thông qua máy chủ thuê GHE.com đã cấu hình.
- Các quyền OAuth được yêu cầu có thể bao gồm quyền truy cập cần thiết để đọc các tổ chức, kho lưu trữ, nhánh, nhập tệp, ghi bản sao lưu và quản lý các hook của kho lưu trữ khi được yêu cầu bởi một quy trình làm việc đồng bộ hóa.
Việc kết nối một máy chủ thuê có khả năng lưu trữ dữ liệu tại chỗ tự nó không chứng minh rằng mọi danh mục dữ liệu liên quan đến GitHub hoặc Apidog đều nằm trong một khu vực. GitHub tài liệu hóa dữ liệu được bao phủ bởi dịch vụ lưu trữ dữ liệu tại chỗ của họ và các trường hợp ngoại lệ liên quan. Apidog là một dịch vụ được kết nối riêng biệt với mô hình lưu trữ và triển khai riêng. Xem lại tài liệu hiện tại của cả hai nhà cung cấp như một phần của đánh giá khả năng lưu trữ dữ liệu tại chỗ hoặc tuân thủ.
Các hướng dẫn quản trị API liên quan:
Các hướng dẫn này bao gồm các kiểm soát bổ sung để quản trị không gian làm việc API doanh nghiệp:
- Khung Quản trị API — kết nối quyền sở hữu, kiểm soát, bằng chứng và các 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ừ các nhóm nhà cung cấp danh tính.
- Trình quét bí mật — xem xét các thông tin xác thực có thể bị lộ trong các tài sản Apidog được hỗ trợ.
- Nhật ký kiểm tra — điều tra và xuất hoạt động quản trị của tổ chức.
- Cung cấp SCIM — quản lý người dùng tổ chức trong suốt vòng đời danh tính.
- Chính sách Doanh nghiệp — cấu hình 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ụ — cho phép các nhóm do thành viên tạo trong khi vẫn duy trì sự giám sát quyền sở hữu.
- Tích hợp GitHub Enterprise Cloud — kết nối các kho lưu trữ GHE.com được hỗ trợ cho các quy trình làm việc OpenAPI.
Tài liệu chính thức liên quan: