Dokumen ini memberikan semua informasi dasar yang Anda perlukan untuk mulai menggunakan library. Materi ini mencakup konsep-konsep perpustakaan, menunjukkan contoh untuk berbagai kasus penggunaan, dan memberikan tautan ke informasi lebih lanjut.
Penyiapan
Ada beberapa langkah penyiapan yang perlu Anda selesaikan sebelum dapat menggunakan library ini:
- Jika Anda belum memiliki Akun Google, daftar.
- Jika Anda belum pernah membuat project Konsol API Google, baca Halaman Mengelola Project dan membuat proyek di Konsol API Google.
- Instal paket NuGet yang ingin Anda gunakan.
Autentikasi dan otorisasi
Penting untuk memahami dasar-dasar cara penanganan otentikasi dan otorisasi API. Semua panggilan API harus menggunakan akses sederhana atau terotorisasi (ditentukan di bawah). Banyak metode API memerlukan akses yang sah, tetapi beberapa metode juga dapat menggunakannya. Beberapa metode API yang bisa menggunakan perilaku yang berbeda, tergantung apakah Anda menggunakan akses sederhana atau terotorisasi. Lihat dokumentasi metode API untuk menentukan jenis akses yang sesuai.
1. Akses API sederhana (kunci API)
Panggilan API ini tidak mengakses data pribadi pengguna. Aplikasi Anda harus mengautentikasi dirinya sendiri sebagai aplikasi yang ke project Konsol API Google Anda. Hal ini diperlukan untuk mengukur penggunaan proyek untuk tujuan akuntansi.
Kunci API: Untuk mengautentikasi aplikasi Anda, gunakan sebuah Kunci API untuk project Konsol API Anda. Setiap panggilan akses sederhana yang dilakukan aplikasi Anda harus menyertakan kunci ini.
2. Akses API yang diizinkan (OAuth 2.0)
Panggilan API ini mengakses data pribadi pengguna. Sebelum Anda dapat melakukan panggilan kepada mereka, pengguna yang memiliki akses ke data pribadi harus memberikan akses aplikasi Anda. Oleh karena itu, aplikasi Anda harus diautentikasi, pengguna harus memberikan akses untuk aplikasi Anda, dan pengguna harus diotentikasi untuk memberikan akses itu. Semua ini dicapai dengan OAuth 2.0 dan library yang ditulis untuknya.
Cakupan: Setiap API mendefinisikan satu atau beberapa cakupan yang mendeklarasikan serangkaian operasi yang diizinkan. Misalnya, API mungkin memiliki cakupan hanya baca dan baca tulis. Saat aplikasi Anda meminta akses ke data pengguna, permintaan harus menyertakan satu atau beberapa cakupan. Pengguna harus menyetujui cakupan akses yang diminta aplikasi Anda.
Token akses dan refresh: Ketika pengguna memberikan akses aplikasi Anda, server otorisasi OAuth 2.0 menyediakan token refresh dan akses ke aplikasi Anda. Token ini hanya valid untuk cakupan yang diminta. Aplikasi Anda menggunakan token akses untuk mengizinkan panggilan API. Masa berlaku token akses habis, tetapi token refresh tidak. Aplikasi Anda dapat menggunakan token refresh untuk memperoleh token akses baru.
Client ID dan rahasia klien: String ini secara unik mengidentifikasi aplikasi Anda dan digunakan untuk memperoleh token. API ini dibuat untuk project Anda di Konsol API. Ada tiga jenis client ID, jadi pastikan untuk mendapatkan jenis yang tepat untuk aplikasi Anda:
- Client ID aplikasi web
- Client ID aplikasi terinstal
- Client ID Akun Layanan
Contoh
Di bagian ini, ada contoh penggunaan API sederhana tanpa otorisasi. Untuk informasi selengkapnya tentang panggilan otorisasi, lihat Halaman OAuth 2.0 untuk .NET.
Contoh API sederhana
Contoh ini menggunakan akses API sederhana untuk aplikasi command line. Fungsi ini memanggil Google Discovery API untuk menampilkan daftar semua Google API.
Misalnya, penyiapan
Mendapatkan kunci API Sederhana. Untuk menemukan kunci API aplikasi Anda, lakukan hal berikut:
- Buka halaman Credentials di Konsol API.
-
API ini mendukung dua jenis kredensial.
Buat kredensial apa pun yang sesuai untuk project Anda:
-
OAuth 2.0: Setiap kali aplikasi Anda meminta pengguna pribadi data, klien harus mengirimkan token OAuth 2.0 bersama dengan permintaan. Nama mula-mula mengirim ID klien dan, mungkin, rahasia klien ke mendapatkan token. Anda dapat membuat kredensial OAuth 2.0 untuk web aplikasi, akun layanan, atau aplikasi terinstal.
Untuk informasi selengkapnya, lihat Dokumentasi OAuth 2.0.
-
Kunci API: Permintaan yang tidak menyediakan token OAuth 2.0 harus mengirimkan API tombol. Kunci ini mengidentifikasi project Anda dan memberikan akses, kuota, dan laporan.
API ini mendukung beberapa jenis pembatasan pada kunci API. Jika kunci API yang Anda yang dibutuhkan, maka buat kunci API di Konsol mengeklik Create credentials > Kunci API. Anda dapat membatasi kunci sebelum menggunakannya dalam produksi dengan mengklik Restrict key dan memilih salah satu Pembatasan.
-
Untuk menjaga keamanan kunci API Anda, ikuti praktik terbaik untuk dengan aman menggunakan kunci API.
Kode misalnya
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);
}
}
}
}
}
Tips untuk menggunakan kunci API:
- Untuk menggunakan layanan tertentu, Anda harus menambahkan referensi ke layanan tersebut. Misalnya, jika Anda ingin menggunakan Tasks API, Anda perlu menginstal paket NuGet-nya Google.Apis.Tasks.v1.
- Untuk membuat instance layanan, cukup panggil konstruktornya. Contoh:
new TasksService(new BaseClientService.Initializer {...});"
. - Semua metode layanan berada di resource individual di objek layanan itu sendiri.
Layanan Discovery memiliki resource
Apis
, yang berisi metodeList
. Saat Anda memanggilservice.Apis.List(..)
, objek permintaan yang menargetkan metode ini akan ditampilkan.
Untuk menjalankan permintaan, panggil metodeExecute()
atauExecuteAsyc()
pada permintaan. - Tetapkan kunci API menggunakan properti
ApiKey
pada instanceBaseClientService.Initializer
.
Menemukan informasi tentang API
Tujuan API yang didukung mencantumkan semua API yang bisa diakses menggunakan library ini serta link ke dokumentasi.
Anda juga dapat menggunakan Penjelajah API menelusuri API, mencantumkan metode yang tersedia, dan bahkan mencoba panggilan API dari browser Anda.