بدء سريع

يمكنك إنشاء تطبيق سطر أوامر بلغة Go يرسل طلبات إلى Google Sheets API.

توضّح أدلة التشغيل السريع كيفية إعداد تطبيق وتشغيله لاستدعاء Google Workspace API. يستخدم دليل التشغيل السريع هذا طريقة مصادقة مبسطة مناسبة لبيئة الاختبار. بالنسبة إلى بيئة التشغيل الفعلي، ننصحك بالتعرّف على المصادقة والتفويض قبل اختيار بيانات الاعتماد المناسبة لتطبيقك.

يستخدم دليل التشغيل السريع هذا مكتبات عملاء واجهة برمجة التطبيقات المقترَحة من Google Workspace للتعامل مع بعض تفاصيل عملية المصادقة والتفويض.

الأهداف

  • إعداد البيئة
  • إعداد النموذج
  • تشغيل النموذج

المتطلبات الأساسية

  • حساب Google

إعداد البيئة

لإكمال دليل التشغيل السريع هذا، عليك إعداد البيئة.

تفعيل واجهة برمجة التطبيقات

قبل استخدام Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيق واحدة أو أكثر في مشروع واحد على Google Cloud.

إذا كنت تستخدم مشروعًا جديدًا على Google Cloud لإكمال دليل التشغيل السريع هذا، عليك إعداد شاشة موافقة OAuth. إذا سبق لك إكمال هذه الخطوة لمشروعك على السحابة الإلكترونية، فانتقل إلى القسم التالي.

  1. في Google API Console، انتقِل إلى "القائمة" > منصة Google للمصادقة > العلامة التجارية.

    الانتقال إلى صفحة "العلامة التجارية"

  2. إذا سبق لك إعداد "منصة Google للمصادقة"، يمكنك إعداد إعدادات شاشة موافقة OAuth التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك رسالة لم يتم إعداد "منصة Google للمصادقة" بعد، انقر على البدء:
    1. ضمن معلومات التطبيق، في اسم التطبيق، أدخِل اسمًا للتطبيق.
    2. في البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريد إلكتروني للدعم يمكن للمستخدمين التواصل معك من خلاله إذا كانت لديهم أسئلة حول موافقتهم.
    3. انقر على التالي.
    4. ضمن الجمهور، اختَر داخلي.
    5. انقر على التالي.
    6. ضمن معلومات الاتصال، أدخِل عنوان بريد إلكتروني يمكنك تلقّي إشعارات من خلاله بشأن أي تغييرات تطرأ على مشروعك.
    7. انقر على التالي.
    8. ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API، وإذا كنت موافقًا عليها، ضَع علامة في المربّع أوافق على سياسة بيانات المستخدمين في خدمات Google API.
    9. انقر على متابعة.
    10. انقر على إنشاء.
  3. يمكنك في الوقت الحالي تخطّي إضافة النطاقات. في المستقبل، عند إنشاء تطبيق لاستخدامه خارج مؤسستك على Google Workspace، عليك تغيير نوع المستخدم إلى خارجي. بعد ذلك، أضِف نطاقات التفويض التي يتطلبها تطبيقك. لمزيد من المعلومات، اطّلِع على دليل إعداد موافقة OAuth الكامل Configure OAuth consent.

السماح ببيانات اعتماد لتطبيق على الكمبيوتر

لمصادقة المستخدمين النهائيين والوصول إلى بيانات المستخدمين في تطبيقك، عليك إنشاء معرّف عميل واحد أو أكثر لبروتوكول OAuth 2.0. يُستخدم معرّف العميل لتعريف تطبيق واحد لخوادم OAuth من Google. إذا كان تطبيقك يعمل على منصات متعددة، عليك إنشاء معرّف عميل منفصل لكل منصة.
  1. في Google Cloud Console، انتقِل إلى "القائمة" > منصة Google للمصادقة > العملاء.

    الانتقال إلى صفحة "العملاء"

  2. انقر على إنشاء عميل.
  3. انقر على نوع التطبيق > تطبيق على الكمبيوتر.
  4. في حقل الاسم ، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في Google Cloud Console.
  5. انقر على إنشاء.

    تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن "معرّفات عملاء OAuth 2.0".

  6. احفظ ملف JSON الذي تم تنزيله باسم credentials.json وانقِل الملف إلى دليل العمل.

إعداد مساحة العمل

  1. أنشِئ دليل عمل:

    mkdir quickstart

  2. انتقِل إلى دليل العمل:

    cd quickstart

  3. ابدأ الوحدة الجديدة:

    go mod init quickstart

  4. احصل على مكتبة عملاء Go لـ Google Sheets API وحزمة OAuth2.0:

    go get google.golang.org/api/sheets/v4
go get golang.org/x/oauth2/google

إعداد النموذج

  1. في دليل العمل، أنشِئ ملفًا باسم quickstart.go.

  2. في الملف، ألصِق الرمز البرمجي التالي:

    sheets/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/sheets/v4"
)

// 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/spreadsheets.readonly")
	if err != nil {
		log.Fatalf("Unable to parse client secret file to config: %v", err)
	}
	client := getClient(config)

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

	// Prints the names and majors of students in a sample spreadsheet:
	// https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit
	spreadsheetId := "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
	readRange := "Class Data!A2:E"
	resp, err := srv.Spreadsheets.Values.Get(spreadsheetId, readRange).Do()
	if err != nil {
		log.Fatalf("Unable to retrieve data from sheet: %v", err)
	}

	if len(resp.Values) == 0 {
		fmt.Println("No data found.")
	} else {
		fmt.Println("Name, Major:")
		for _, row := range resp.Values {
			// Print columns A and E, which correspond to indices 0 and 4.
			fmt.Printf("%s, %s\n", row[0], row[4])
		}
	}
}

تشغيل النموذج

  1. في دليل العمل، أنشِئ النموذج وشغِّله:

    go run quickstart.go
  1. في المرة الأولى التي تشغِّل فيها النموذج، سيُطلب منك السماح بالوصول:
    1. إذا لم يسبق لك تسجيل الدخول إلى حساب Google، سجِّل الدخول عندما يُطلب منك ذلك. إذا كنت مسجِّلاً الدخول إلى حسابات متعددة، اختَر حسابًا واحدًا لاستخدامه في التفويض.
    2. انقر على حسنًا.

    يتم تشغيل تطبيق Go ويستدعي Google Sheets API.

    يتم تخزين معلومات التفويض في نظام الملفات، لذا لن يُطلب منك التفويض في المرة التالية التي تشغِّل فيها نموذج الرمز البرمجي.

الخطوات التالية