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

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

ตั้งค่า

คุณต้องทำตามขั้นตอนการตั้งค่า 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 ทั้งหมดที่สามารถเข้าถึงได้โดยใช้ไลบรารีนี้ รวมถึงลิงก์ไปยังเอกสารประกอบ

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