เอกสารนี้มีข้อมูลพื้นฐานทั้งหมดที่จำเป็นในการเริ่มใช้งานไลบรารี ซึ่งครอบคลุมแนวคิดของไลบรารี แสดงตัวอย่างสำหรับกรณีการใช้งานต่างๆ และให้ลิงก์ไปยังข้อมูลเพิ่มเติม
ตั้งค่า
คุณต้องทำตามขั้นตอนการตั้งค่า 2-3 ขั้นตอนก่อนจึงจะใช้คลังนี้ได้ ดังนี้
- หากยังไม่มีบัญชี 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 ในคอนโซลโดยคลิกสร้างข้อมูลเข้าสู่ระบบ > คีย์ 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 จากเบราว์เซอร์ได้อีกด้วย