เอกสารนี้จะให้ข้อมูลเบื้องต้นทั้งหมดที่คุณจําเป็นต้องทราบเพื่อเริ่มใช้ไลบรารี โดยจะครอบคลุมแนวคิดของไลบรารี แสดงตัวอย่างกรณีการใช้งานต่างๆ และให้ลิงก์ไปยังข้อมูลเพิ่มเติม
ตั้งค่า
คุณต้องทําตามขั้นตอนการตั้งค่าไม่กี่ขั้นตอนก่อนจึงจะใช้ไลบรารีนี้ได้
- หากคุณยังไม่มีบัญชี Google โปรดลงชื่อสมัครใช้
- หากคุณไม่เคยสร้างโปรเจ็กต์คอนโซล Google API ให้อ่านหน้าการจัดการโปรเจ็กต์และสร้างโปรเจ็กต์ในคอนโซล Google API
- ติดตั้งแพ็กเกจ 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 ของแอปพลิเคชัน ให้ทําตามขั้นตอนต่อไปนี้
- เปิดหน้าข้อมูลเข้าสู่ระบบในคอนโซล API
-
API นี้รองรับข้อมูลเข้าสู่ระบบ 2 ประเภท
สร้างข้อมูลเข้าสู่ระบบที่เหมาะกับโปรเจ็กต์ของคุณ ดังนี้
-
OAuth 2.0: เมื่อใดก็ตามที่แอปพลิเคชันส่งคําขอข้อมูลส่วนตัวของผู้ใช้ แอปพลิเคชันจะต้องส่งโทเค็น OAuth 2.0 พร้อมด้วยคําขอ แอปพลิเคชันของคุณจะส่งรหัสไคลเอ็นต์ไปก่อน และอาจรวมถึงรหัสลับไคลเอ็นต์เพื่อรับโทเค็น คุณสามารถสร้างข้อมูลเข้าสู่ระบบ OAuth 2.0 สําหรับเว็บแอปพลิเคชัน บัญชีบริการ หรือแอปพลิเคชันที่ติดตั้งไว้ได้
สําหรับข้อมูลเพิ่มเติม โปรดดูเอกสาร OAuth 2.0
-
คีย์ API: คําขอที่ไม่มีโทเค็น OAuth 2.0 ต้องส่งคีย์ API คีย์จะระบุโปรเจ็กต์และให้สิทธิ์เข้าถึง API โควต้า และรายงาน
API รองรับข้อจํากัดหลายประเภทในคีย์ API หากไม่มีคีย์ API ที่ต้องการอยู่แล้ว ให้สร้างคีย์ API ในคอนโซลโดยคลิกสร้างข้อมูลเข้าสู่ระบบ & gt; คีย์ 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 Explorer เพื่อเรียกดู API แสดงรายการเมธอดที่ใช้ได้ หรือจะลองใช้การเรียก API จากเบราว์เซอร์ก็ได้เช่นกัน