go github

Go-github

Go-Github เป็นไลบรารีไคลเอนต์ GO สำหรับการเข้าถึง GitHub API V3

Go-Github ต้องการ GO เวอร์ชัน 1.17 และยิ่งใหญ่กว่า และห้องสมุดได้รับการทดสอบกับ GO เวอร์ชัน 1.22 และมากกว่า นโยบายการสนับสนุนเวอร์ชัน Go-github ของ Go เราพยายามอย่างดีที่สุดที่จะไม่ทำลายรุ่นเก่าถ้าเราไม่ต้องทำ แต่เนื่องจากข้อ จำกัด ด้านเครื่องมือเราไม่ได้ทดสอบรุ่นเก่าเสมอไป

หากคุณสนใจที่จะใช้ GraphQL API V4 ไลบรารีที่แนะนำคือ Shurcool/GitHubv4

การติดตั้ง

Go-github เข้ากันได้กับการเปิดตัว GO ที่ทันสมัยในโหมดโมดูลโดยติดตั้ง GO:

go get github.com/google/go-github/v68

จะแก้ไขและเพิ่มแพ็คเกจลงในโมดูลการพัฒนาปัจจุบันพร้อมกับการพึ่งพา

อีกทางเลือกหนึ่งสามารถทำได้หากคุณใช้การนำเข้าในแพ็คเกจ:

 import "github.com/google/go-github/v68/github"

และเรียกใช้ go get โดยไม่ต้องพารามิเตอร์

ในที่สุดหากต้องการใช้ repo รุ่นบนสุดของ repo นี้ให้ใช้คำสั่งต่อไปนี้:

go get github.com/google/go-github/v68@master

การใช้งาน

 import "github.com/google/go-github/v68/github"	// with go modules enabled (GO111MODULE=on or outside GOPATH)
import "github.com/google/go-github/github" // with go modules disabled

สร้างไคลเอนต์ GitHub ใหม่จากนั้นใช้บริการต่าง ๆ บนไคลเอนต์เพื่อเข้าถึงส่วนต่าง ๆ ของ GitHub API ตัวอย่างเช่น:

 client := github . NewClient ( nil )

// list all organizations for user "willnorris"
orgs , _ , err := client . Organizations . List ( context . Background (), "willnorris" , nil )

วิธี API บางวิธีมีพารามิเตอร์เสริมที่สามารถผ่านได้ ตัวอย่างเช่น:

 client := github . NewClient ( nil )

// list public repositories for org "github"
opt := & github. RepositoryListByOrgOptions { Type : "public" }
repos , _ , err := client . Repositories . ListByOrg ( context . Background (), "github" , opt )

บริการของลูกค้าแบ่ง API ออกเป็นก้อนตรรกะและสอดคล้องกับโครงสร้างของเอกสาร GitHub API

หมายเหตุ: การใช้แพ็คเกจบริบทหนึ่งสามารถส่งสัญญาณการยกเลิกและกำหนดเวลาไปยังบริการต่างๆของลูกค้าเพื่อจัดการคำขอ ในกรณีที่ไม่มีบริบท context.Background() สามารถใช้เป็นจุดเริ่มต้น

สำหรับตัวอย่างโค้ดตัวอย่างเพิ่มเติมตรงไปที่ไดเรกทอรีตัวอย่าง

การรับรองความถูกต้อง

ใช้วิธี WithAuthToken เพื่อกำหนดค่าไคลเอนต์ของคุณเพื่อตรวจสอบสิทธิ์โดยใช้โทเค็น OAuth (ตัวอย่างเช่นโทเค็นการเข้าถึงส่วนบุคคล) นี่คือสิ่งที่จำเป็นสำหรับกรณีการใช้งานส่วนใหญ่นอกเหนือจากแอพ GitHub

 client := github . NewClient ( nil ). WithAuthToken ( "... your access token ..." )

โปรดทราบว่าเมื่อใช้ไคลเอนต์ที่ผ่านการรับรองความถูกต้องการโทรทั้งหมดที่ลูกค้าทำจะรวมโทเค็น OAuth ที่ระบุไว้ ดังนั้นลูกค้าที่ได้รับการรับรองความถูกต้องไม่ควรแชร์ระหว่างผู้ใช้ที่แตกต่างกัน

สำหรับวิธี API ที่ต้องใช้การตรวจสอบความถูกต้องพื้นฐาน HTTP ให้ใช้ BasicAuthTransport

เป็นแอพ GitHub

การรับรองความถูกต้องของแอพ GitHub สามารถให้ได้โดย PKGs ที่แตกต่างกันเช่น Bradleyfalzon/Ghinstallation หรือ Jferrl/Go-Githubauth

หมายเหตุ : จุดสิ้นสุดส่วนใหญ่ (เช่น GET /rate_limit ) ต้องการการเข้าถึงการตรวจสอบโทเค็นในขณะที่อีกสองสามคน (เช่น GET /app/hook/deliveries ) ต้องการการตรวจสอบ JWT

ghinstallation ให้ Transport ซึ่งใช้ http.RoundTripper เพื่อให้การรับรองความถูกต้องเป็นการติดตั้งสำหรับแอพ GitHub

นี่คือตัวอย่างของวิธีการตรวจสอบความถูกต้องเป็นแอพ GitHub โดยใช้แพ็คเกจ ghinstallation :

 import (
	"net/http"

	"github.com/bradleyfalzon/ghinstallation/v2"
	"github.com/google/go-github/v68/github"
)

func main () {
	// Wrap the shared transport for use with the integration ID 1 authenticating with installation ID 99.
	itr , err := ghinstallation . NewKeyFromFile ( http . DefaultTransport , 1 , 99 , "2016-10-19.private-key.pem" )

	// Or for endpoints that require JWT authentication
	// itr, err := ghinstallation.NewAppsTransportKeyFromFile(http.DefaultTransport, 1, "2016-10-19.private-key.pem")

	if err != nil {
		// Handle error.
	}

	// Use installation transport with client.
	client := github . NewClient ( & http. Client { Transport : itr })

	// Use client...
}

go-githubauth ใช้ชุดของ oauth2.TokenSource ที่จะใช้กับ oauth2.Client oauth2.Client สามารถฉีดเข้าไปใน github.Client เพื่อตรวจสอบสิทธิ์คำขอ

ตัวอย่างอื่น ๆ โดยใช้ go-githubauth :

 package main

import (
	"context"
	"fmt"
	"os"
	"strconv"

	"github.com/google/go-github/v68/github"
	"github.com/jferrl/go-githubauth"
	"golang.org/x/oauth2"
)

func main () {
	privateKey := [] byte ( os . Getenv ( "GITHUB_APP_PRIVATE_KEY" ))

	appTokenSource , err := githubauth . NewApplicationTokenSource ( 1112 , privateKey )
	if err != nil {
		fmt . Println ( "Error creating application token source:" , err )
		return
	 }

	installationTokenSource := githubauth . NewInstallationTokenSource ( 1113 , appTokenSource )

	// oauth2.NewClient uses oauth2.ReuseTokenSource to reuse the token until it expires.
	// The token will be automatically refreshed when it expires.
	// InstallationTokenSource has the mechanism to refresh the token when it expires.
	httpClient := oauth2 . NewClient ( context . Background (), installationTokenSource )

	client := github . NewClient ( httpClient )
}

หมายเหตุ : ในการโต้ตอบกับ API บางอย่างเช่นการเขียนไฟล์ไปยัง repo หนึ่งต้องสร้างโทเค็นการติดตั้งโดยใช้รหัสการติดตั้งของแอพ GitHub และตรวจสอบสิทธิ์ด้วยวิธี OAuth ที่กล่าวถึงข้างต้น ดูตัวอย่าง

อัตราการ จำกัด

GitHub กำหนดขีด จำกัด อัตราของลูกค้า API ทั้งหมด ลูกค้าที่ไม่ผ่านการตรวจสอบจะถูก จำกัด ไว้ที่ 60 คำขอต่อชั่วโมงในขณะที่ลูกค้าที่ได้รับการรับรองความถูกต้องสามารถทำเงินได้มากถึง 5,000 คำขอต่อชั่วโมง API การค้นหามีขีด จำกัด อัตราที่กำหนดเอง ลูกค้าที่ไม่ผ่านการตรวจสอบจะถูก จำกัด ไว้ที่ 10 คำขอต่อนาทีในขณะที่ลูกค้าที่ได้รับการรับรองความถูกต้องสามารถขอได้มากถึง 30 คำขอต่อนาที ในการรับขีด จำกัด อัตราที่สูงขึ้นเมื่อทำการโทรที่ไม่ได้ออกในนามของผู้ใช้ให้ใช้ UnauthenticatedRateLimitedTransport

ค่า Response.Rate กลับที่ส่งคืนอัตราการ จำกัด มีข้อมูลขีด จำกัด อัตราจากการโทร API ล่าสุด หากไม่มีการตอบสนองที่เพียงพอเมื่อเร็ว ๆ นี้คุณสามารถใช้ RateLimits เพื่อดึงข้อมูลขีด จำกัด อัตราที่ทันสมัยที่สุดสำหรับไคลเอนต์

ในการตรวจสอบข้อผิดพลาดในการ จำกัด อัตรา API คุณสามารถตรวจสอบได้ว่าประเภทของมันคือ *github.RateLimitError :

 repos , _ , err := client . Repositories . List ( ctx , "" , nil )
if _ , ok := err .( * github. RateLimitError ); ok {
	log . Println ( "hit rate limit" )
}

เรียนรู้เพิ่มเติมเกี่ยวกับอัตราการ จำกัด อัตรา GitHub ใน "จุดสิ้นสุด REST API สำหรับการ จำกัด อัตรา"

นอกเหนือจากการ จำกัด อัตราเหล่านี้ GitHub กำหนดขีด จำกัด อัตรารองสำหรับไคลเอนต์ API ทั้งหมด ขีด จำกัด อัตรานี้ป้องกันไม่ให้ลูกค้าทำการร้องขอพร้อมกันมากเกินไป

ในการตรวจสอบข้อผิดพลาดการ จำกัด อัตรารอง API คุณสามารถตรวจสอบได้ว่าประเภทของมันคือ *github.AbuseRateLimitError :

 repos , _ , err := client . Repositories . List ( ctx , "" , nil )
if _ , ok := err .( * github. AbuseRateLimitError ); ok {
	log . Println ( "hit secondary rate limit" )
}

อีกทางเลือกหนึ่งคุณสามารถบล็อกจนกว่าขีด จำกัด อัตราจะถูกรีเซ็ตโดยใช้ context.WithValue วิธี:

 repos , _ , err := client . Repositories . List ( context . WithValue ( ctx , github . SleepUntilPrimaryRateLimitResetWhenRateLimited , true ), "" , nil )

คุณสามารถใช้ gofri/go-github-ratelimit เพื่อจัดการกับการ จำกัด อัตราการนอนหลับและการเรียนรู้สำหรับคุณ

เรียนรู้เพิ่มเติมเกี่ยวกับ GitHub อัตรารอง จำกัด ใน "เกี่ยวกับการ จำกัด อัตรารอง"

สถานะที่ยอมรับ

จุดสิ้นสุดบางจุดอาจส่งคืนรหัสสถานะที่ยอมรับได้ 202 ซึ่งหมายความว่าข้อมูลที่ต้องการยังไม่พร้อมและมีกำหนดจะรวบรวมทางด้าน GitHub วิธีการที่รู้จักกันในการทำเช่นนี้มีการบันทึกไว้เพื่อระบุพฤติกรรมนี้

ในการตรวจสอบเงื่อนไขของข้อผิดพลาดนี้คุณสามารถตรวจสอบว่าประเภทของมันคือ *github.AcceptedError :

 stats , _ , err := client . Repositories . ListContributorsStats ( ctx , org , repo )
if _ , ok := err .( * github. AcceptedError ); ok {
	log . Println ( "scheduled on GitHub side" )
}

คำขอตามเงื่อนไข

GitHub API ได้รับการสนับสนุนที่ดีสำหรับการร้องขอตามเงื่อนไขซึ่งจะช่วยป้องกันไม่ให้คุณเผาไหม้ผ่านขีด จำกัด อัตราของคุณรวมถึงช่วยเร่งแอปพลิเคชันของคุณ go-github ไม่จัดการคำขอตามเงื่อนไขโดยตรง แต่ได้รับการออกแบบมาเพื่อทำงานกับการแคช http.Transport แทน เราขอแนะนำให้ใช้ gregjones/httpcache สำหรับสิ่งนั้น ตัวอย่างเช่น:

 import "github.com/gregjones/httpcache"

	client := github . NewClient (
		httpcache . NewMemoryCacheTransport (). Client ()
    ). WithAuthToken ( os . Getenv ( "GITHUB_TOKEN" ))

เรียนรู้เพิ่มเติมเกี่ยวกับคำขอตามเงื่อนไขของ GitHub ใน "ใช้คำขอตามเงื่อนไขหากเหมาะสม"

การสร้างและอัปเดตทรัพยากร

โครงสร้างทั้งหมดสำหรับทรัพยากร GitHub ใช้ค่าตัวชี้สำหรับฟิลด์ที่ไม่ได้ทำซ้ำทั้งหมด สิ่งนี้จะช่วยให้แยกแยะระหว่างฟิลด์ UNSET และที่ตั้งค่าเป็นค่าศูนย์ ฟังก์ชั่นผู้ช่วยได้รับการจัดเตรียมเพื่อสร้างพอยน์เตอร์เหล่านี้สำหรับสตริงบูลและค่า int ได้อย่างง่ายดาย ตัวอย่างเช่น:

 // create a new private repository named "foo"
repo := & github. Repository {
	Name :    github . Ptr ( "foo" ),
	Private : github . Ptr ( true ),
}
client . Repositories . Create ( ctx , "" , repo )

ผู้ใช้ที่เคยทำงานกับบัฟเฟอร์โปรโตคอลควรค้นหารูปแบบนี้ที่คุ้นเคย

การปนเปื้อน

คำขอทั้งหมดสำหรับการรวบรวมทรัพยากร (repos, คำขอดึงปัญหา ฯลฯ ) สนับสนุนการปนเปื้อน ตัวเลือกการปนเปื้อนอธิบายไว้ในโครงสร้าง github.ListOptions และส่งผ่านไปยังวิธีการรายการโดยตรงหรือเป็นประเภทฝังตัวของตัวเลือกรายการที่เฉพาะเจาะจงมากขึ้น struct (ตัวอย่างเช่น github.PullRequestListOptions ) ข้อมูลหน้าเว็บสามารถใช้ได้ผ่าน github.Response struct

 client := github . NewClient ( nil )

opt := & github. RepositoryListByOrgOptions {
	ListOptions : github. ListOptions { PerPage : 10 },
}
// get all pages of results
var allRepos [] * github. Repository
for {
	repos , resp , err := client . Repositories . ListByOrg ( ctx , "github" , opt )
	if err != nil {
		return err
	}
	allRepos = append ( allRepos , repos ... )
	if resp . NextPage == 0 {
		break
	}
	opt . Page = resp . NextPage
}

ตัววนซ้ำ ( ทดลอง )

Go v1.23 แนะนำ iter ใหม่

ด้วยแพ็คเกจ enrichman/gh-iter เป็นไปได้ที่จะสร้างตัววนซ้ำสำหรับ go-github ตัววนซ้ำจะจัดการการปนเปื้อนให้คุณวนรอบผลลัพธ์ทั้งหมดที่มีอยู่

 client := github . NewClient ( nil )
var allRepos [] * github. Repository

// create an iterator and start looping through all the results
repos := ghiter . NewFromFn1 ( client . Repositories . ListByOrg , "github" )
for repo := range repos . All () {
	allRepos = append ( allRepos , repo )
}

สำหรับการใช้งานของ enrichman/gh-iter ที่สมบูรณ์ให้ดูเอกสารแพ็คเกจเต็มรูปแบบ

webhooks

go-github จัดเตรียมโครงสร้างสำหรับกิจกรรม GitHub WebHook เกือบทั้งหมดรวมถึงฟังก์ชั่นเพื่อตรวจสอบความถูกต้องและ payload unmarshal JSON จาก http.Request structs

 func ( s * GitHubEventMonitor ) ServeHTTP ( w http. ResponseWriter , r * http. Request ) {
	payload , err := github . ValidatePayload ( r , s . webhookSecretKey )
	if err != nil { ... }
	event , err := github . ParseWebHook ( github . WebHookType ( r ), payload )
	if err != nil { ... }
	switch event := event .( type ) {
	case * github. CommitCommentEvent :
		processCommitCommentEvent ( event )
	case * github. CreateEvent :
		processCreateEvent ( event )
	...
	}
}

นอกจากนี้ยังมีไลบรารีเช่น CBRGM/GITHUBEVENTS ที่สร้างขึ้นตามตัวอย่างด้านบนและให้ฟังก์ชั่นเพื่อสมัครสมาชิกการโทรกลับไปยังเหตุการณ์เฉพาะ

สำหรับการใช้งานที่สมบูรณ์ของ Go-Github ให้ดูเอกสารแพ็คเกจเต็มรูปแบบ

รหัสทดสอบที่ใช้ go-github

repo migueleleliasweb/go-github-mock เป็นวิธีการเยาะเย้ยการตอบสนอง ตรวจสอบ Repo สำหรับรายละเอียดเพิ่มเติม

การทดสอบการรวม

คุณสามารถเรียกใช้การทดสอบการรวมจากไดเรกทอรี test ดูการทดสอบการรวม readme

การบริจาค

ฉันอยากจะครอบคลุม GitHub API ทั้งหมดและการบริจาคแน่นอนว่ายินดีต้อนรับเสมอ รูปแบบการโทรนั้นค่อนข้างดีดังนั้นการเพิ่มวิธีการใหม่จึงค่อนข้างตรงไปตรงมา ดู CONTRIBUTING.md สำหรับรายละเอียด

การกำหนดเวอร์ชัน

โดยทั่วไปแล้ว Go-Github จะติดตาม Semver อย่างใกล้ชิดที่สุดเท่าที่จะทำได้สำหรับการติดแท็กรีลีสของแพ็คเกจ สำหรับห้องสมุดที่มีอยู่ในตัวเองแอปพลิเคชันการกำหนดเวอร์ชันความหมายค่อนข้างตรงไปตรงมาและเข้าใจโดยทั่วไป แต่เนื่องจาก Go-Github เป็นไลบรารีลูกค้าสำหรับ GitHub API ซึ่งเปลี่ยนพฤติกรรมและเนื่องจากโดยทั่วไปแล้วเราค่อนข้างก้าวร้าวเกี่ยวกับการใช้คุณสมบัติตัวอย่างของ GitHub API เราจึงได้นำนโยบายการกำหนดเวอร์ชันต่อไปนี้มาใช้:

• เราเพิ่ม เวอร์ชันหลัก ด้วยการเปลี่ยนแปลงที่เข้ากันไม่ได้กับฟังก์ชั่นที่ไม่ได้ตรวจสอบรวมถึงการเปลี่ยนแปลงพื้นผิว GO API ที่ส่งออกหรือพฤติกรรมของ API
• เราเพิ่ม เวอร์ชันรอง ด้วยการเปลี่ยนแปลงที่เข้ากันได้กับการทำงานรวมถึงการเปลี่ยนแปลงใด ๆ ในการทำงานตัวอย่างใน GitHub API GitHub ไม่รับประกันเกี่ยวกับความเสถียรของฟังก์ชั่นการแสดงตัวอย่างดังนั้นเราจึงไม่คิดว่ามันเป็นส่วนที่มั่นคงของ Go-Github API
• เราเพิ่ม เวอร์ชันแพตช์ ด้วยการแก้ไขข้อผิดพลาดที่เข้ากันได้กับด้านหลัง

ฟังก์ชั่นการดูตัวอย่างอาจใช้รูปแบบของวิธีการทั้งหมดหรือเพียงแค่ข้อมูลเพิ่มเติมที่ส่งคืนจากวิธีการไม่ผ่านการตรวจสอบเป็นอย่างอื่น อ้างถึงเอกสาร GitHub API สำหรับรายละเอียดเกี่ยวกับฟังก์ชั่นการแสดงตัวอย่าง

การกำหนดเวอร์ชันปฏิทิน

ณ ปี 2022-11-28 GitHub ได้ประกาศว่าพวกเขากำลังเริ่มต้นเวอร์ชัน V3 API ของพวกเขาตาม "การดูปฏิทิน"

ในทางปฏิบัติเป้าหมายของเราคือการทำให้เวอร์ชันต่อวิธีการแทนที่ (อย่างน้อยในห้องสมุดหลัก) หายากและชั่วคราว

ความเข้าใจของเราเกี่ยวกับเอกสาร GitHub คือพวกเขาจะปรับปรุง API ทั้งหมดให้กับเวอร์ชันที่ใช้วันที่ใหม่แต่ละรุ่นแม้ว่าจะมีเพียงไม่กี่วิธีเท่านั้นที่มีการเปลี่ยนแปลง วิธีอื่น ๆ จะยอมรับเวอร์ชันใหม่ด้วยฟังก์ชั่นที่มีอยู่ ดังนั้นเมื่อ GitHub API เวอร์ชันวันที่ใหม่ได้รับการปล่อยตัวเรา (ผู้ดูแล Repo) วางแผนที่จะ:

• อัปเดตแต่ละวิธีที่มีการเปลี่ยนแปลงการเปลี่ยนแปลงส่วนหัวของรุ่น API ต่อวิธีการของพวกเขา สิ่งนี้อาจเกิดขึ้นได้ในหนึ่งหรือหลายครั้งและ PRS และทำทั้งหมดในสาขาหลัก

• เมื่อวิธีการทั้งหมดที่มีการเปลี่ยนแปลงการเปลี่ยนแปลงได้รับการอัปเดตแล้วให้มีการกระทำขั้นสุดท้ายที่กระแทกเวอร์ชัน API เริ่มต้นและลบการแทนที่ด้วยวิธีการทั้งหมด ตอนนี้จะได้รับการชนรุ่นใหญ่เมื่อมีการเปิดตัว Go-Github ครั้งต่อไป

ตารางความเข้ากันได้ของเวอร์ชัน

ตารางต่อไปนี้ระบุว่า GitHub API เวอร์ชันใดได้รับการสนับสนุนโดยเวอร์ชัน (และอดีต) ของ repo นี้ (go-github) เวอร์ชันก่อน 48.2.0 จะไม่อยู่ในรายการ

Go-github เวอร์ชัน	GitHub V3 API เวอร์ชัน
68.0.0	2022-11-28
-	2022-11-28
48.2.0	2022-11-28

ใบอนุญาต

ห้องสมุดนี้มีการแจกจ่ายภายใต้ใบอนุญาตสไตล์ BSD ที่พบในไฟล์ใบอนุญาต