מדריך למתחילים

מדריכים למתחילים מסבירים איך להגדיר ולהפעיל אפליקציה שמתקשרת Google Workspace API.

המדריכים למתחילים של Google Workspace משתמשים בספריות הלקוח של ה-API כדי לטפל פרטים על תהליך האימות וההרשאה. מומלץ להשתמש בספריות הלקוח עבור האפליקציות שלכם. המדריך למתחילים הזה משתמש גישת אימות פשוטה שמתאימה לבדיקות הסביבה. בסביבת ייצור, מומלץ ללמוד על אימות והרשאה לפני בחירת פרטי הכניסה שמתאימים לאפליקציה שלכם.

ליצור אפליקציית שורת הפקודה Go ששולחת בקשות Google Apps Script API.

מטרות

  • מגדירים את הסביבה.
  • הגדרת הדוגמה.
  • מריצים את הדוגמה.

דרישות מוקדמות

  • חשבון Google ש-Google Drive מופעל בו.

הגדרת הסביבה

כדי להשלים את המדריך למתחילים הזה, עליכם להגדיר את הסביבה.

הפעלת ה-API

לפני שמשתמשים ב-Google APIs, צריך להפעיל אותם בפרויקט ב-Google Cloud. אפשר להפעיל ממשק API אחד או יותר בפרויקט אחד ב-Google Cloud.

אם אתם משתמשים בפרויקט חדש ב-Google Cloud כדי להשלים את המדריך למתחילים הזה, צריך להגדיר מסך ההסכמה ל-OAuth ולהוסיף את עצמכם כמשתמש/ת בדיקה. אם כבר סיימתם את השלב הזה בפרויקט שלכם ב-Cloud, דלגו לחלק הבא.

  1. במסוף Google Cloud, נכנסים לתפריט > ממשקי API ו- שירותים > מסך ההסכמה של OAuth.

    מעבר למסך ההסכמה ל-OAuth

  2. בקטע סוג המשתמש, בוחרים באפשרות פנימי ולוחצים על יצירה.
  3. ממלאים את טופס הרישום של האפליקציה ולוחצים על שמירה והמשך.

  4. בשלב הזה אפשר לדלג על הוספת היקפי הרשאות וללחוץ על שמירה והמשך. בעתיד, כשתיצרו אפליקציה לשימוש מחוץ ל- בארגון ב-Google Workspace, צריך לשנות את סוג המשתמש לחיצוני, ואז: להוסיף את היקפי ההרשאות שנדרשים לאפליקציה.

  5. מעיינים בסיכום של רישום האפליקציה. כדי לבצע שינויים, לוחצים על עריכה. אם האפליקציה נראה שהרישום תקין, לוחצים על חזרה למרכז הבקרה.

אישור פרטי כניסה לאפליקציה בשולחן העבודה

כדי לאמת משתמשי קצה ולגשת לנתוני המשתמשים באפליקציה: ליצור מזהה לקוח אחד או יותר של OAuth 2.0. מזהה לקוח משמש לזיהוי אפליקציה יחידה לשרתי OAuth של Google. אם האפליקציה שלכם פועלת בכמה פלטפורמות, צריך ליצור מזהה לקוח נפרד לכל פלטפורמה.
  1. במסוף Google Cloud, נכנסים לתפריט > APIs & שירותים > פרטי כניסה.

    כניסה לדף Credentials

  2. לוחצים על יצירת פרטי כניסה > מזהה לקוח OAuth.
  3. לוחצים על סוג אפליקציה > אפליקציית מחשב.
  4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.
  5. לוחצים על יצירה. יופיע המסך שנוצר על ידי לקוח OAuth ומוצג בו מזהה הלקוח החדש וסוד הלקוח שלכם.
  6. לוחצים על אישור. פרטי הכניסה החדשים שנוצרו יופיעו בקטע מזהי לקוחות OAuth 2.0.
  7. שומרים את קובץ ה-JSON שהורדתם בתור credentials.json ומעבירים את לספריית העבודה.

הכנת סביבת העבודה

  1. יוצרים ספריית עבודה:

    mkdir quickstart

  2. שינוי לספריית העבודה:

    cd quickstart

  3. מאתחלים את המודול החדש:

    go mod init quickstart

  4. מקבלים את ספריית הלקוח של Google Apps Script API Go וחבילת OAuth2.0:

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

הגדרת הדוגמה

  1. בספריית העבודה, יוצרים קובץ בשם quickstart.go.

  2. בקובץ, מדביקים את הקוד הבא:

    apps_script/quickstart/quickstart.go
    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/script/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, "https://www.googleapis.com/auth/script.projects")
	if err != nil {
		log.Fatalf("Unable to parse client secret file to config: %v", err)
	}
	client := getClient(config)

	srv, err := script.NewService(ctx, option.WithHTTPClient(client))
	if err != nil {
		log.Fatalf("Unable to retrieve Script client: %v", err)
	}

	req := script.CreateProjectRequest{Title: "My Script"}
	createRes, err := srv.Projects.Create(&req).Do()
	if err != nil {
		// The API encountered a problem.
		log.Fatalf("The API returned an error: %v", err)
	}
	content := &script.Content{
		ScriptId: createRes.ScriptId,
		Files: []*script.File{{
			Name:   "hello",
			Type:   "SERVER_JS",
			Source: "function helloWorld() {\n  console.log('Hello, world!');}",
		}, {
			Name: "appsscript",
			Type: "JSON",
			Source: "{\"timeZone\":\"America/New_York\",\"exceptionLogging\":" +
				"\"CLOUD\"}",
		}},
	}
	updateContentRes, err := srv.Projects.UpdateContent(createRes.ScriptId,
		content).Do()
	if err != nil {
		// The API encountered a problem.
		log.Fatalf("The API returned an error: %v", err)
	}
	log.Printf("https://script.google.com/d/%v/edit", updateContentRes.ScriptId)
}

הרצת הדוגמה

  1. בספריית העבודה, יוצרים ומריצים את הדוגמה:

    go run quickstart.go
  1. בפעם הראשונה שמריצים את הדוגמה, מוצגת בקשה לאשר גישה:
    1. אם עדיין לא נכנסתם לחשבון Google, נכנסים אליו כשמוצגת בקשה לעשות זאת. אם המיקום נכנסת לכמה חשבונות. צריך לבחור חשבון אחד שישמש להרשאה.
    2. לוחצים על אישור.

    אפליקציית Go מריצה את Google Apps Script API וקוראת לו להפעיל אותו.

    פרטי ההרשאות מאוחסנים במערכת הקבצים, לכן בפעם הבאה שמריצים את הדוגמה לא תופיע בקשה להרשאה.

השלבים הבאים