Dokumen ini memberikan semua informasi dasar yang Anda perlukan untuk mulai menggunakan library. Halaman ini mencakup konsep library, menampilkan contoh untuk berbagai kasus penggunaan, dan memberikan link ke informasi selengkapnya.
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 buat project di Konsol API Google.
- Instal paket NuGet yang ingin Anda gunakan.
Autentikasi dan otorisasi
Penting untuk memahami dasar-dasar cara penanganan dan autentikasi API. Semua panggilan API harus menggunakan akses sederhana atau yang diotorisasi (ditentukan di bawah). Banyak metode API memerlukan akses yang sah, tetapi beberapa metode juga dapat menggunakan keduanya. Beberapa metode API yang dapat menggunakan perilaku berbeda, bergantung pada apakah Anda menggunakan akses sederhana atau diotorisasi. Lihat dokumentasi metode API untuk menentukan jenis akses yang sesuai.
1. Akses API sederhana (kunci API)
Panggilan API ini tidak mengakses data pengguna pribadi. Aplikasi Anda harus mengautentikasi dirinya sendiri sebagai aplikasi milik project Konsol API Google Anda. Informasi ini diperlukan untuk mengukur penggunaan project untuk tujuan akuntansi.
Kunci API: Untuk mengautentikasi aplikasi, gunakan kunci API untuk project Konsol API Anda. Setiap panggilan akses sederhana yang dilakukan aplikasi Anda harus menyertakan kunci ini.
2. Akses API resmi (OAuth 2.0)
Panggilan API ini mengakses data pengguna pribadi. Sebelum Anda dapat memanggil pengguna, pengguna yang memiliki akses ke data pribadi tersebut harus memberikan akses aplikasi Anda. Oleh karena itu, aplikasi Anda harus diautentikasi, pengguna harus memberikan akses untuk aplikasi Anda, dan pengguna harus diautentikasi agar dapat memberikan akses tersebut. Semua ini dapat dilakukan dengan OAuth 2.0 dan library yang ditulis untuknya.
Cakupan: Setiap API menentukan satu atau beberapa cakupan yang mendeklarasikan sekumpulan operasi yang diizinkan. Misalnya, API mungkin memiliki cakupan hanya baca dan tulis. Saat aplikasi Anda meminta akses ke data pengguna, permintaan tersebut harus menyertakan satu atau beberapa cakupan. Pengguna harus menyetujui cakupan akses yang diminta aplikasi Anda.
Token refresh dan akses: Jika pengguna memberikan akses aplikasi Anda, server otorisasi OAuth 2.0 akan 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. Token akses berakhir masa berlakunya, tetapi token refresh tidak berlaku. 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 mendapatkan token. Kebijakan tersebut dibuat untuk project Anda di Konsol API. Ada tiga jenis client ID, jadi pastikan untuk mendapatkan jenis yang benar untuk aplikasi Anda:
- Client ID aplikasi web
- Client ID aplikasi yang diinstal
- ID klien 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. Ini memanggil Google Discovery API untuk mencantumkan semua Google API.
Penyiapan misalnya
Dapatkan kunci API Sederhana Anda. 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 meminta data pengguna pribadi, aplikasi harus mengirimkan token OAuth 2.0 beserta permintaannya. Aplikasi Anda mengirim client ID terlebih dahulu dan mungkin rahasia klien untuk mendapatkan token. Anda dapat membuat kredensial OAuth 2.0 untuk aplikasi web, akun layanan, atau aplikasi terinstal.
Untuk informasi selengkapnya, lihat dokumentasi OAuth 2.0.
-
Kunci API: Permintaan yang tidak memberikan token OAuth 2.0 harus mengirim kunci API. Kunci tersebut mengidentifikasi project Anda dan memberikan akses, kuota, dan laporan API.
API ini mendukung beberapa jenis pembatasan pada kunci API. Jika kunci API yang Anda butuhkan belum ada, buat kunci API di Console dengan mengklik Create credentials > API key. Anda dapat membatasi kunci sebelum menggunakannya dalam produksi dengan mengklik Restrict key dan memilih salah satu Restrictions.
-
Untuk menjaga keamanan kunci API Anda, ikuti praktik terbaik untuk menggunakan kunci API secara aman.
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 harus menginstal paket NuGet Google.Apis.Tasks.v1.
- Untuk membuat instance layanan, cukup panggil konstruktornya. Contoh:
new TasksService(new BaseClientService.Initializer {...});"
. - Semua metode layanan berada di resource individual pada 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
Halaman API yang didukung mencantumkan semua API yang dapat diakses menggunakan library ini serta link ke dokumentasi.
Anda juga dapat menggunakan APIs Explorer untuk mencari API, mencantumkan metode yang tersedia, dan bahkan mencoba panggilan API dari browser Anda.