本文件提供開始使用程式庫所需的所有基本資訊。其中會說明程式庫概念、顯示各種用途的範例，並提供更多資訊的連結。
設定
您必須先完成幾個步驟，才能使用這個程式庫：
- 如果您還沒有 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 都會定義一或多個範圍，宣告一組允許的作業。舉例來說，API 可能有唯讀和讀寫範圍。當應用程式要求存取使用者資料時，要求必須包含一或多個範圍。使用者必須核准應用程式要求的存取權範圍。
重新整理和存取權杖：當使用者授予應用程式存取權時，OAuth 2.0 授權伺服器會為您的應用程式提供重新整理和存取權杖。這些權杖只適用於要求的範圍。您的應用程式會使用存取權杖來授權 API 呼叫。存取權杖會過期，但重新整理權杖則不會。應用程式可以使用更新權杖來取得新的存取權杖。
用戶端 ID 和用戶端密鑰：這些字串專門用來識別您的應用程式，並用來取得權杖。您可以在 API 控制台中為專案建立這個名稱。用戶端 ID 有三種類型，因此請務必取得應用程式正確的類型：
範例
本節將舉例說明未授權的簡易 API 用法。如要進一步瞭解授權呼叫，請參閱 .NET 適用的 OAuth 2.0 頁面。
簡易 API 範例
本範例針對指令列應用程式使用簡易的 API 存取權。它會呼叫 Google Discovery API 來列出所有 Google API。
範例設定
取得 Simple API 金鑰。如要找出應用程式的 API 金鑰，請按照下列步驟操作：
- 在 API 控制台中開啟「憑證」頁面。
-
這個 API 支援兩種憑證。建立適合您專案的憑證：
-
OAuth 2.0：每當您的應用程式要求私人使用者資料時，都必須與要求一併傳送 OAuth 2.0 權杖。應用程式會先傳送用戶端 ID，並可能傳送用戶端密鑰來取得權杖。您可以為網路應用程式、服務帳戶或已安裝的應用程式產生 OAuth 2.0 憑證。
詳情請參閱 OAuth 2.0 說明文件。
-
API 金鑰：沒有提供 OAuth 2.0 權杖的要求必須傳送 API 金鑰。金鑰可用來識別專案，並提供 API 存取權、配額和報表。
API 支援數種類型的 API 金鑰限制。如果您還沒有所需的 API 金鑰，請依序點按「Create credentials」(建立憑證) >「API key」(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 {...});"。 - 服務的所有方法都位於服務物件本身的個別資源上。探索服務具有
Apis資源，包含List方法。呼叫service.Apis.List(..)時，系統會傳回指定這個方法的要求物件。
如要執行要求，請對要求呼叫Execute()或ExecuteAsyc()方法。 - 在
BaseClientService.Initializer執行個體上使用ApiKey屬性設定 API 金鑰。
尋找 API 相關資訊
「支援的 API」頁面會列出可透過這個程式庫存取的所有 API，以及說明文件連結。
您也可以使用 APIs Explorer 瀏覽 API、列出可用方法，甚至試用瀏覽器中的 API 呼叫。