Краткое руководство по Go

Создайте приложение командной строки Go, которое отправляет запросы к People API.

В руководствах по быстрому началу работы объясняется, как настроить и запустить приложение, вызывающее Google Workspace API. В этом руководстве по быстрому началу работы используется упрощенный подход к аутентификации, подходящий для тестовой среды. Для рабочей среды рекомендуем ознакомиться с информацией об аутентификации и авторизации, прежде чем выбирать учетные данные для доступа, подходящие для вашего приложения.

В этом руководстве по быстрому началу работы используются рекомендованные клиентские библиотеки API Google Workspace, которые обрабатывают некоторые детали процесса аутентификации и авторизации.

Цели

• Настройте среду.
• Настройте образец.
• Запустите пример.

Требования

• Последняя версия Go.
• Последняя версия Git.
• Проект Google Cloud.

• Домен Google Workspace с включенным доступом к API.
• Аккаунт Google в этом домене с правами администратора.

Как настроить среду

Чтобы выполнить инструкции из этого руководства, настройте среду.

Включение API

Прежде чем использовать API Google, их нужно включить в облачном проекте Google Cloud. В одном облачном проекте Google Cloud можно включить один или несколько API.

• В консоли Google Cloud включите People API.

  Включите API

Как настроить окно запроса доступа OAuth

Если вы используете новый проект Google Cloud, настройте окно запроса доступа OAuth. Если вы уже выполнили этот шаг для своего облачного проекта, перейдите к следующему разделу.

1. В консоли API Google нажмите на значок меню > Платформа аутентификации Google > Брендинг.

   Перейти к брендингу

2. Если вы уже настроили платформу аутентификации Google, вы можете задать следующие настройки окна запроса доступа OAuth в разделах Брендинг, Аудитория и Доступ к данным. Если вы видите сообщение Google Auth platform not configured yet (Платформа Google Auth ещё не настроена), нажмите Get Started (Начать).
1. В разделе Информация о приложении в поле Название приложения введите название приложения.
2. В поле Электронный адрес службы поддержки укажите адрес, по которому пользователи смогут обращаться с вопросами о согласии.
3. Нажмите Далее.
4. В разделе Аудитория выберите Внутренние.
5. Нажмите Далее.
6. В разделе Контактная информация укажите адрес электронной почты, на который будут приходить уведомления об изменениях в проекте.
7. Нажмите Далее.
8. В разделе Finish (Завершение) ознакомьтесь с Правилами в отношении пользовательских данных сервисов API Google и, если вы согласны с ними, установите флажок I agree to the Google API Services: User Data Policy (Я принимаю Правила в отношении пользовательских данных сервисов API Google).
9. Нажмите Продолжить.
10. Нажмите Создать.
3. Пока вы можете пропустить добавление областей действия. Если в будущем вы создадите приложение для использования за пределами организации Google Workspace, вам нужно будет изменить тип пользователя на Внешний. Затем добавьте области авторизации, необходимые вашему приложению. Подробную информацию можно найти в руководстве по настройке запроса согласия OAuth.

Как авторизовать учетные данные для компьютерного приложения

Чтобы аутентифицировать конечных пользователей и получить доступ к их данным в приложении, создайте один или несколько идентификаторов клиента OAuth 2.0. Идентификатор клиента используется для идентификации одного приложения на серверах OAuth Google. Если ваше приложение работает на нескольких платформах, для каждой из них необходимо создать отдельный идентификатор клиента.

1. В консоли Google Cloud нажмите на значок меню > Google Auth platform (Платформа Google Auth) > Clients (Клиенты).

   Перейти в раздел "Клиенты"

2. Нажмите Создать клиента.
3. Нажмите Тип приложения > Компьютерное приложение.
4. В поле Название введите название учетных данных. Это название показывается только в консоли Google Cloud.
5. Если ваше приложение – это ИИ-агент, который выполняет действия от имени пользователей, выберите Использовать этот клиент для агента на основе ИИ. Если ваше приложение поддерживает как рабочие процессы ИИ-агентов, так и стандартные функции для пользователей, создайте отдельные клиенты OAuth для каждого из них. После создания клиента изменить эту настройку нельзя.
6. Нажмите Создать.

   Созданные учетные данные появятся в разделе "Идентификаторы клиентов OAuth 2.0".

7. Сохраните скачанный JSON-файл под названием credentials.json и переместите его в рабочую папку.

Подготовка рабочей области

1. Создайте рабочий каталог:

   mkdir quickstart
   

2. Перейдите в рабочий каталог:

   cd quickstart
   

3. Инициализируйте новый модуль:

   go mod init quickstart
   

4. Получите клиентскую библиотеку People API Go и пакет OAuth 2.0:

   go get google.golang.org/api/people/v1
   go get golang.org/x/oauth2/google
   

Настройка образца

1. В рабочем каталоге создайте файл с названием quickstart.go.

2. Вставьте в файл следующий код:

   people/quickstart/quickstart.go

   Посмотреть на GitHub
   package main
   
   import (
   	"context"
   	"encoding/json"
   	"fmt"
   	"log"
   	"net/http"
   	"os"
   
   	"golang.org/x/oauth2"
   	"golang.org/x/oauth2/google"
   	"google.golang.org/api/option"
   	"google.golang.org/api/people/v1"
   )
   
   // 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, people.ContactsReadonlyScope)
   	if err != nil {
   		log.Fatalf("Unable to parse client secret file to config: %v", err)
   	}
   	client := getClient(config)
   
   	srv, err := people.NewService(ctx, option.WithHTTPClient(client))
   	if err != nil {
   		log.Fatalf("Unable to create people Client %v", err)
   	}
   
   	r, err := srv.People.Connections.List("people/me").PageSize(10).
   		PersonFields("names,emailAddresses").Do()
   	if err != nil {
   		log.Fatalf("Unable to retrieve people. %v", err)
   	}
   	if len(r.Connections) > 0 {
   		fmt.Print("List 10 connection names:\n")
   		for _, c := range r.Connections {
   			names := c.Names
   			if len(names) > 0 {
   				name := names[0].DisplayName
   				fmt.Printf("%s\n", name)
   			}
   		}
   	} else {
   		fmt.Print("No connections found.")
   	}
   }

Запустите пример

1. В рабочем каталоге создайте и запустите пример:

   go run quickstart.go
   

2. При первом запуске примера вам будет предложено авторизовать доступ:
   1. Если вы ещё не вошли в аккаунт Google, сделайте это. Если вы вошли в несколько аккаунтов, выберите один из них для авторизации.
   2. Нажмите Принимаю.

   Приложение Go запустится и вызовет People API.

   Информация об авторизации сохраняется в файловой системе, поэтому при следующем запуске примера кода вам не потребуется проходить авторизацию.

Дальнейшие действия

• Попробуйте Google Workspace API в API Explorer
  • Как устранить неполадки с аутентификацией и авторизацией
  • Справочная документация по People API
  • Раздел google-api-go-client на GitHub