使用 GitHub-API 的 GitHub Java API
1. 簡介
在本文中，我們將了解GitHub API For Java函式庫。這為我們提供了GitHib API的物件導向表示，使我們能夠輕鬆地從 Java 應用程式與其進行互動。
2.依賴項
要使用 GitHub API for Java 函式庫，我們需要在建置中包含最新版本，目前是 1.327 。
如果我們使用 Maven，我們可以在pom.xml檔案中包含這個依賴項：
<dependency>
<groupId>org.kohsuke</groupId>
<artifactId>github-api</artifactId>
<version>1.327</version>
</dependency>此時，我們已準備好開始在我們的應用程式中使用它。
3. 客戶端創建
為了使用該函式庫，我們首先需要建立一個GitHub客戶端實例。這是與 GitHub API 互動的主要入口點。
建立此實例的最簡單方法是匿名連線：
GitHub gitHub = GitHub.connectAnonymously();這樣我們無需任何身份驗證憑證就可以存取 API。然而，我們能做的僅限於那些可以以這種方式運作的功能。
或者，我們可以使用憑證進行連線：
GitHub gitHub = GitHub.connect();這樣做會嘗試透過幾種不同的方式來確定要使用的憑證：
- 如果設定了環境屬性
GITHUB_OAUTH，那麼這將用作個人存取權杖。 - 否則，如果設定了環境屬性
GITHUB_JWT，這將用作 JWT 令牌。 - 否則，如果同時設定了
GITHUB_LOGIN和GITHUB_PASSWORD，那麼它們將直接用作憑證。 - 否則，我們將嘗試使用使用者主目錄中的
.github properties檔案來提供等效屬性。在這種情況下，名稱將採用小寫形式，且不帶GITHUB_前綴。
如果這些值都不可用，則建立用戶端將會失敗。
我們也可以選擇透過手動提供憑證來建立客戶端：
GitHub github = new GitHubBuilder().withOAuthToken("my_personal_token").build();
GitHub github = new GitHubBuilder().withJwtToken("my_jwt_token").build();
GitHub github = new GitHubBuilder().withPassword("my_user", "my_password").build();如果我們選擇使用其中一個，那麼我們就可以從任何我們希望的地方載入適當的憑證。
另請注意，圖書館僅在需要時才使用這些憑證。這意味著，如果提供的憑證無效，我們只有在以需要身份驗證的方式與 API 互動時才會發現。如果我們使用任何以匿名方式運作的 API 方法，那麼這些方法將繼續運作。
4. 我和其他用戶
一旦我們建立了客戶端，我們就可以開始與 GitHub API 互動。
如果我們有一個正確驗證的客戶端，那麼我們可以使用它來查詢我們已驗證的用戶 - 即Myself:
GHMyself myself = gitHub.getMyself();然後我們可以使用該物件來查詢當前使用者：
assertEquals("someone", myself.getLogin());
assertEquals("[email protected]", myself.getEmail());
assertEquals(50, myself.getFollows().size());我們也可以查詢其他用戶的詳細資訊：
GHUser user = gitHub.getUser("eugenp");
assertEquals("eugenp", user.getLogin());
assertEquals(2, user.getFollows().size());這將會傳回一個GHUser ，它是GHMyself的超類別。因此，我們可以對GHMyself物件（代表目前經過身份驗證的使用者）執行某些操作，而不能對任何其他使用者執行這些操作。這些包括：
- 管理公鑰
- 管理電子郵件地址
- 管理組織會員資格
但是，任何需要GHUser東西也可以接受GHMyself 。
5. 儲存庫
我們還可以與儲存庫以及用戶合作。這將包括查詢使用者擁有的儲存庫清單的能力，還包括存取儲存庫的內容甚至對其進行更改的能力。
請注意，GitHub 中的所有儲存庫都只屬於一個用戶，因此我們需要知道用戶名稱以及儲存庫名稱才能正確存取它們。
5.1.列出儲存庫
如果我們有一個GHUser物件 - 或GHMyself –那麼我們可以使用它來取得該使用者擁有的儲存庫。這是使用listRepositories()實現的：
PagedIterable<GHRepository> repositories = user.listRepositories();由於這些儲存庫的數量可能非常多，因此這為我們提供了一個PagedIterable 。預設情況下，這適用於頁面大小為 30 的情況，但如果需要，我們可以在列出儲存庫時指定它：
PagedIterable<GHRepository> repositories = user.listRepositories(50);這給我們提供了多種存取實際儲存庫的方法。我們可以將其轉換為包含整個儲存庫集合的Array 、 List或Set類型：
Array<GHRepository> repositoriesArray = repositories.toArray();
List<GHRepository> repositoriesList = repositories.toList();
Set<GHRepository> repositoriesSet = repositories.toSet();然而，這些都需要預先收取所有費用——如果數量非常大的話，費用可能會很昂貴。例如， Microsoft 使用者目前擁有 6,688 個儲存庫。每頁有 30 個儲存庫，需要 223 個 API 呼叫才能收集完整清單。
或者，我們可以取得儲存庫的迭代器。這樣就只會根據需要進行 API 呼叫，讓我們更有效率地存取集合：
Iterator<GHRepository> repositoriesSet = repositories.toIterator();但更簡單的是， PagedIterable本身是一個Iterable ，可以在任何適用的地方直接使用 - 例如，在增強的 for 循環中：
Set<String> names = new HashSet<>();
for (GHRepository ghRepository : user.listRepositories()) {
names.add(ghRepository.getName());
}
這只是遍歷每個返回的存儲庫並提取它們的名稱。因為我們使用的是PagedIterable ，它將像普通的Iterable一樣運行，但僅在必要時才會在背景進行 API 呼叫。
5.2.直接存取儲存庫
除了列出儲存庫之外，我們還可以直接透過名稱存取它們。如果我們有了適當的GHUser ，那麼我們只需要儲存庫名稱：
GHRepository repository = user.getRepository("tutorials");或者，我們可以直接從客戶端存取儲存庫。在這種情況下，我們需要將使用者名稱和儲存庫名稱組合成一個字串的全名：
GHRepository repository = gitHub.getRepository("eugenp/tutorials");這樣，我們就得到了完全相同的GHRepository對象，就像我們透過GHUser對象導航一樣.
5.3.使用儲存庫
一旦我們獲得了GHRepository對象，我們就可以開始直接與它互動。
在最簡單的層面上，這允許我們檢索存儲庫詳細信息，例如其名稱、所有者、創建日期等。
String name = repository.getName();
String fullName = repository.getFullName();
GHUser owner = repository.getOwner();
Date created = repository.getCreatedAt();但是，我們也可以查詢儲存庫的內容。我們可以將其視為 Git 儲存庫來實現這一點 - 允許存取分支、標籤、提交等：
String defaultBranch = repository.getDefaultBranch();
GHBranch branch = repository.getBranch(defaultBranch);
String branchHash = branch.getSHA1();
GHCommit commit = repository.getCommit(branchHash);
System.out.println(commit.getCommitShortInfo().getMessage());
或者，如果我們知道全名，那麼我們就可以存取文件的全部內容：
String defaultBranch = repository.getDefaultBranch();
GHContent file = repository.getFileContent("pom.xml", defaultBranch);
String fileContents = IOUtils.toString(file.read(), Charsets.UTF_8);如果它們存在，我們也可以存取某些特殊文件 - 具體來說，就是自述文件和許可證：
GHContent readme = repository.getReadme();
GHContent license = repository.getLicenseContent();這些工作與直接存取文件完全相同，但不需要知道文件名。特別是，GitHub 支援這些概念的一系列不同的檔案名，並且它將傳回正確的檔案名稱。
5.4.操作儲存庫
除了讀取儲存庫內容，我們還可以對其進行更改。
這可以包括更新儲存庫本身的配置，允許我們執行諸如更改描述、主頁、可見性等操作：
repository.setDescription("A new description");
repository.setVisibility(GHRepository.Visibility.PRIVATE);
我們也可以將其他儲存庫分叉到我們自己的帳戶：
repository.createFork().name("my_fork").create();我們還可以建立分支、標籤、拉取請求和其他內容：
repository.createRef("new-branch", oldBranch.getSHA1());
repository.createTag("new-tag", "This is a tag", branch.getSHA1(), "commit");
repository.createPullRequest("new-pr", "from-branch", "to-branch", "Description of the pull request");如果需要的話，我們甚至可以創建完整的提交，儘管這更加複雜。
6. 結論
在本文中，我們對 GitHub API For Java 函式庫進行了簡要介紹。使用這個庫還可以做更多的事情。下次您需要使用 GitHub API 時，為什麼不嘗試一下呢。
與往常一樣，本文中的所有範例都可以在 GitHub 上找到。