本文件提供開始使用程式庫所需的所有基本資訊。 其中內容包括程式庫概念、顯示各種用途的範例，並提供更多資訊的連結。
設定
您必須先完成幾個設定步驟，才能使用這個程式庫：
- 如果您還沒有 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 金鑰不存在，則在主控台中依序按一下「建立憑證」>「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 {...});"。 - 服務的所有方法都位於服務物件本身的個別資源上。探索服務具有包含
List方法的Apis資源。當您呼叫service.Apis.List(..)時，系統會傳回針對此方法的要求物件。
如要執行要求，請針對要求呼叫Execute()或ExecuteAsyc()方法。 - 使用
BaseClientService.Initializer例項上的ApiKey屬性設定 API 金鑰。
尋找 API 的相關資訊
支援的 API 頁面會列出可透過這個程式庫存取的所有 API 以及說明文件連結。
您也可以使用 APIs Explorer 瀏覽 API、列出可用方法，甚至透過瀏覽器試用 API 呼叫。