Go 快速入門導覽課程

建立 Go 指令列應用程式，向 Directory API 發出要求。

快速入門導覽課程會說明如何設定及執行應用程式，來呼叫 Google Workspace API。本快速入門導覽課程會使用簡化的驗證方法，適用於測試環境。在正式環境中，建議您先瞭解驗證和授權，再選擇適合應用程式的存取憑證。

本快速入門導覽課程使用 Google Workspace 建議的 API 用戶端程式庫，處理驗證和授權流程的部分詳細資料。

目標

• 設定環境。
• 設定範例。
• 執行範例。

必要條件

• 最新版本 Go。
• 最新版本的 Git。
• Google Cloud 專案。

• 已啟用 API 存取權的 Google Workspace 網域。
• 網域中須包含具備管理員權限的 Google 帳戶。

設定環境

如要完成這項快速入門導覽課程，請設定環境。

啟用 API

您必須先在 Google Cloud 專案中啟用 Google API，才能使用。您可以在單一 Google Cloud 專案中啟用一或多個 API。

• 在 Google Cloud 控制台中啟用 Directory API。

  啟用 API

設定 OAuth 同意畫面

如果您使用新的 Google Cloud 雲端專案完成這項快速入門導覽課程，請設定 OAuth 同意畫面。如果您已為 Cloud 專案完成這個步驟，請跳到下一節。

1. 在 Google API 控制台中，依序前往「Menu」(選單) >「Google Auth platform」>「Branding」(品牌)。

   前往「Branding」(品牌宣傳)

2. 如果您已設定 Google 驗證平台，可以在「Branding」(品牌)、「Audience」(目標對象) 和「Data Access」(資料存取權) 中設定下列 OAuth 同意畫面設定。如果看到「尚未設定 Google 驗證平台」訊息，請按一下「開始使用」：
1. 在「App Information」下方的「App name」中，輸入應用程式名稱。
2. 在「User support email」(使用者支援電子郵件) 中，選擇支援電子郵件地址，方便使用者在同意聲明方面有任何疑問時與您聯絡。
3. 點選 [Next] (下一步)。
4. 在「Audience」(目標對象) 下方，選取「Internal」(內部)。
5. 點選 [Next] (下一步)。
6. 在「Contact Information」(聯絡資訊) 下方，輸入可接收專案異動通知的電子郵件地址。
7. 點選 [Next] (下一步)。
8. 在「Finish」(完成) 部分，請詳閱《Google API 服務使用者資料政策》，然後選取「我同意《Google API 服務：使用者資料政策》」。
9. 按一下 [Continue] (繼續)。
10. 按一下「Create」(建立)。
3. 目前可以略過新增範圍。 日後，如果您建立的應用程式要用於 Google Workspace 組織外部，請務必將「User type」(使用者類型) 變更為「External」(外部)。然後新增應用程式需要的授權範圍。詳情請參閱完整的設定 OAuth 同意畫面指南。

授權電腦應用程式的憑證

如要驗證使用者身分並存取應用程式中的使用者資料，您需要建立一或多個 OAuth 2.0 用戶端 ID。Google 的 OAuth 伺服器會使用用戶端 ID 來識別個別應用程式。如果應用程式在多個平台執行，請務必為每個平台分別建立用戶端 ID。

1. 在 Google Cloud 控制台中，依序前往「Menu」(選單) >「Google Auth platform」(Google Auth 平台) >「Clients」(用戶端)。

   前往「Clients」(客戶) 頁面

2. 按一下「Create Client」(建立用戶端)。
3. 依序點選「Application type」(應用程式類型) >「Desktop app」(電腦版應用程式)。
4. 在「Name」欄位中輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
5. 選用：如果您的應用程式是 AI 代理，可代表使用者執行動作，請選取「讓 AI 代理使用這個用戶端」。如果應用程式同時支援 AI 代理工作流程和標準使用者功能，請分別建立不同的 OAuth 用戶端。用戶端建立後即無法變更這項設定。
6. 按一下 [Create] (建立)。

   新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。

7. 將下載的 JSON 檔案儲存為 credentials.json，然後將該檔案移至目前使用的目錄。

準備工作區

1. 建立目前使用的目錄：

   mkdir quickstart
   

2. 變更為目前使用的目錄：

   cd quickstart
   

3. 初始化新模組：

   go mod init quickstart
   

4. 取得 Directory API Go 用戶端程式庫和 OAuth2.0 套件：

   go get google.golang.org/api/admin/directory/v1
   go get golang.org/x/oauth2/google
   

設定範例

1. 在目前使用的目錄中，建立名為 quickstart.go 的檔案。

2. 在檔案中貼上下列程式碼：

   admin_sdk/directory/quickstart.go

   前往 GitHub 查看
   package main
   
   import (
   	"context"
   	"encoding/json"
   	"fmt"
   	"log"
   	"net/http"
   	"os"
   
   	"golang.org/x/oauth2"
   	"golang.org/x/oauth2/google"
   	admin "google.golang.org/api/admin/directory/v1"
   	"google.golang.org/api/option"
   )
   
   // Retrieve a token, saves the token, then returns the generated client.
   func getClient(config *oauth2.Config) *http.Client {
   	// The file token.json stores the user's access and refresh tokens, and is
   	// created automatically when the authorization flow completes for the first
   	// time.
   	tokFile := "token.json"
   	tok, err := tokenFromFile(tokFile)
   	if err != nil {
   		tok = getTokenFromWeb(config)
   		saveToken(tokFile, tok)
   	}
   	return config.Client(context.Background(), tok)
   }
   
   // Request a token from the web, then returns the retrieved token.
   func getTokenFromWeb(config *oauth2.Config) *oauth2.Token {
   	authURL := config.AuthCodeURL("state-token", oauth2.AccessTypeOffline)
   	fmt.Printf("Go to the following link in your browser then type the "+
   		"authorization code: \n%v\n", authURL)
   
   	var authCode string
   	if _, err := fmt.Scan(&authCode); err != nil {
   		log.Fatalf("Unable to read authorization code: %v", err)
   	}
   
   	tok, err := config.Exchange(context.TODO(), authCode)
   	if err != nil {
   		log.Fatalf("Unable to retrieve token from web: %v", err)
   	}
   	return tok
   }
   
   // Retrieves a token from a local file.
   func tokenFromFile(file string) (*oauth2.Token, error) {
   	f, err := os.Open(file)
   	if err != nil {
   		return nil, err
   	}
   	defer f.Close()
   	tok := &oauth2.Token{}
   	err = json.NewDecoder(f).Decode(tok)
   	return tok, err
   }
   
   // Saves a token to a file path.
   func saveToken(path string, token *oauth2.Token) {
   	fmt.Printf("Saving credential file to: %s\n", path)
   	f, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0600)
   	if err != nil {
   		log.Fatalf("Unable to cache oauth token: %v", err)
   	}
   	defer f.Close()
   	json.NewEncoder(f).Encode(token)
   }
   
   func main() {
   	ctx := context.Background()
   	b, err := os.ReadFile("credentials.json")
   	if err != nil {
   		log.Fatalf("Unable to read client secret file: %v", err)
   	}
   
   	// If modifying these scopes, delete your previously saved token.json.
   	config, err := google.ConfigFromJSON(b, admin.AdminDirectoryUserReadonlyScope)
   	if err != nil {
   		log.Fatalf("Unable to parse client secret file to config: %v", err)
   	}
   	client := getClient(config)
   
   	srv, err := admin.NewService(ctx, option.WithHTTPClient(client))
   	if err != nil {
   		log.Fatalf("Unable to retrieve directory Client %v", err)
   	}
   
   	r, err := srv.Users.List().Customer("my_customer").MaxResults(10).
   		OrderBy("email").Do()
   	if err != nil {
   		log.Fatalf("Unable to retrieve users in domain: %v", err)
   	}
   
   	if len(r.Users) == 0 {
   		fmt.Print("No users found.\n")
   	} else {
   		fmt.Print("Users:\n")
   		for _, u := range r.Users {
   			fmt.Printf("%s (%s)\n", u.PrimaryEmail, u.Name.FullName)
   		}
   	}
   }

執行範例

1. 在目前使用的目錄中，建構並執行範例：

   go run quickstart.go
   

2. 首次執行範例時，系統會提示您授予存取權：
   1. 如果尚未登入 Google 帳戶，請在系統提示時登入。如果登入多個帳戶，請選取要用於授權的帳戶。
   2. 按一下 [接受]。

   Go 應用程式會執行並呼叫 Directory API。

   授權資訊會儲存在檔案系統中，因此下次執行程式碼範例時，系統不會提示您授權。

後續步驟

• 在 APIs Explorer 中試用 Google Workspace API
  • 疑難排解驗證和授權問題
  • Directory API 開發人員指南
  • Directory API 參考文件
  • GitHub 的 google-api-go-client 專區