เริ่มต้นใช้งาน

เอกสารนี้มีข้อมูลพื้นฐานทั้งหมดที่จำเป็นในการเริ่มใช้งานไลบรารี ซึ่งครอบคลุมแนวคิดของไลบรารี แสดงตัวอย่างสำหรับกรณีการใช้งานต่างๆ และให้ลิงก์ไปยังข้อมูลเพิ่มเติม

ตั้งค่า

คุณต้องทำตามขั้นตอนการตั้งค่า 2-3 ขั้นตอนก่อนจึงจะใช้คลังนี้ได้ ดังนี้

1. หากยังไม่มีบัญชี Google โปรดลงชื่อสมัครใช้
2. หากคุณไม่เคยสร้างโปรเจ็กต์คอนโซล Google API โปรดอ่านหน้าการจัดการโปรเจ็กต์และสร้างโปรเจ็กต์ในคอนโซล Google API
3. ติดตั้งแพ็กเกจ NuGet ที่คุณต้องการใช้งาน

การตรวจสอบสิทธิ์และการให้สิทธิ์

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

1. การเข้าถึง API แบบง่าย (คีย์ API)

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

คีย์ API: หากต้องการตรวจสอบสิทธิ์แอปพลิเคชัน ให้ใช้คีย์ API สำหรับโปรเจ็กต์คอนโซล API การเรียกใช้การเข้าถึงอย่างง่ายทุกรายการที่แอปพลิเคชันของคุณสร้างขึ้นต้องมีคีย์นี้

2. การเข้าถึง API ที่ได้รับอนุญาต (OAuth 2.0)

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

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

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

รหัสไคลเอ็นต์และรหัสลับไคลเอ็นต์: สตริงเหล่านี้จะระบุแอปพลิเคชันของคุณโดยเฉพาะและใช้เพื่อรับโทเค็น ซึ่งจะสร้างขึ้นสำหรับโครงการในคอนโซล API รหัสไคลเอ็นต์มี 3 ประเภท ดังนั้นอย่าลืมใช้ประเภทที่ถูกต้องสำหรับแอปพลิเคชันของคุณ

• รหัสไคลเอ็นต์ของเว็บแอปพลิเคชัน
• รหัสไคลเอ็นต์แอปพลิเคชันที่ติดตั้ง
• รหัสไคลเอ็นต์ของบัญชีบริการ

ตัวอย่าง

ในส่วนนี้จะมีตัวอย่างการใช้ API แบบง่ายโดยไม่ได้รับอนุญาต ดูข้อมูลเพิ่มเติมเกี่ยวกับการเรียกใช้การให้สิทธิ์ได้ที่หน้า OAuth 2.0 สำหรับ .NET

ตัวอย่าง API แบบง่าย

ตัวอย่างนี้ใช้การเข้าถึง API แบบง่ายสำหรับแอปพลิเคชันบรรทัดคำสั่ง เรียกใช้ Google Discovery API เพื่อแสดง Google API ทั้งหมด

ตัวอย่างการตั้งค่า

รับคีย์ API แบบง่าย หากต้องการค้นหาคีย์ API ของแอปพลิเคชัน ให้ทำดังนี้

1. เปิดหน้าข้อมูลเข้าสู่ระบบในคอนโซล API
2. API นี้รองรับข้อมูลเข้าสู่ระบบ 2 ประเภท สร้างข้อมูลเข้าสู่ระบบที่เหมาะสมกับโปรเจ็กต์ดังนี้

   • OAuth 2.0: เมื่อใดก็ตามที่แอปพลิเคชันขอข้อมูลส่วนตัวของผู้ใช้ แอปพลิเคชันจะต้องส่งโทเค็น OAuth 2.0 ไปพร้อมกับคำขอ แอปพลิเคชันจะส่งรหัสไคลเอ็นต์ก่อน และอาจรวมถึงรหัสลับไคลเอ็นต์เพื่อรับโทเค็น คุณสร้างข้อมูลเข้าสู่ระบบ OAuth 2.0 สำหรับเว็บแอปพลิเคชัน บัญชีบริการ หรือแอปพลิเคชันที่ติดตั้งไว้ได้

     โปรดดูข้อมูลเพิ่มเติมในเอกสารประกอบเกี่ยวกับ OAuth 2.0

   • คีย์ API: คำขอที่ไม่มีโทเค็น OAuth 2.0 ต้องส่งคีย์ API คีย์จะระบุโปรเจ็กต์และให้สิทธิ์เข้าถึง API, โควต้า และรายงาน

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

โปรดทำตามแนวทางปฏิบัติแนะนำสำหรับการใช้คีย์ API อย่างปลอดภัยเพื่อรักษาคีย์ API ให้ปลอดภัย

ตัวอย่างโค้ด

using System;
using System.Threading.Tasks;

using Google.Apis.Discovery.v1;
using Google.Apis.Discovery.v1.Data;
using Google.Apis.Services;

namespace Discovery.ListAPIs
{
    /// <summary>
    /// This example uses the discovery API to list all APIs in the discovery repository.
    /// https://developers.google.com/discovery/v1/using.
    /// <summary>
    class Program
    {
        [STAThread]
        static void Main(string[] args)
        {
            Console.WriteLine("Discovery API Sample");
            Console.WriteLine("====================");
            try
            {
                new Program().Run().Wait();
            }
            catch (AggregateException ex)
            {
                foreach (var e in ex.InnerExceptions)
                {
                    Console.WriteLine("ERROR: " + e.Message);
                }
            }
            Console.WriteLine("Press any key to continue...");
            Console.ReadKey();
        }

        private async Task Run()
        {
            // Create the service.
            var service = new DiscoveryService(new BaseClientService.Initializer
                {
                    ApplicationName = "Discovery Sample",
                    ApiKey="[YOUR_API_KEY_HERE]",
                });

            // Run the request.
            Console.WriteLine("Executing a list request...");
            var result = await service.Apis.List().ExecuteAsync();

            // Display the results.
            if (result.Items != null)
            {
                foreach (DirectoryList.ItemsData api in result.Items)
                {
                    Console.WriteLine(api.Id + " - " + api.Title);
                }
            }
        }
    }
}

เคล็ดลับในการใช้คีย์ API

• ในการใช้บริการที่เจาะจง คุณต้องเพิ่มข้อมูลอ้างอิงของบริการนั้น ตัวอย่างเช่น หากต้องการใช้ Tasks API คุณควรติดตั้งแพ็กเกจ NuGet ของ Google.Apis.Tasks.v1
• หากต้องการสร้างอินสแตนซ์ของบริการ เพียงเรียกใช้ตัวสร้างของบริการ เช่น new TasksService(new BaseClientService.Initializer {...});"
• เมธอดทั้งหมดของบริการจะอยู่ในทรัพยากรแต่ละรายการบนออบเจ็กต์บริการเอง บริการ Discovery มีทรัพยากร Apis ซึ่งมีเมธอด List เมื่อคุณเรียกใช้ service.Apis.List(..) ออบเจ็กต์คำขอที่กำหนดเป้าหมายไปยังเมธอดนี้จะปรากฏขึ้น
  หากต้องการดำเนินการตามคำขอ ให้เรียกใช้เมธอด Execute() หรือ ExecuteAsyc() ในคำขอ
• ตั้งค่าคีย์ API โดยใช้พร็อพเพอร์ตี้ ApiKey ในอินสแตนซ์ BaseClientService.Initializer

การค้นหาข้อมูลเกี่ยวกับ API

หน้า API ที่รองรับจะแสดง API ทั้งหมดที่เข้าถึงได้โดยใช้ไลบรารีนี้ รวมถึงลิงก์ไปยังเอกสารประกอบด้วย

นอกจากนี้คุณยังใช้โปรแกรมสำรวจ API เพื่อเรียกดู API แสดงรายการเมธอดที่พร้อมใช้งาน หรือลองใช้การเรียก API จากเบราว์เซอร์ได้อีกด้วย