開始使用

本文件提供開始使用程式庫的所有基本資訊。 課程中會探討程式庫的概念 顯示了各種用途的範例 並提供詳細資訊的連結

設定

您必須先完成幾個步驟才能使用這個程式庫：

  1. 如果您還沒有 Google 帳戶 註冊。
  2. 如果您從未建立過 Google API 控制台專案，請參閱 管理專案頁面 並在 GCP 控制台中建立 Google API 控制台。
  3. 安裝您要使用的 NuGet 套件。

驗證及授權

請務必瞭解 API 驗證和授權處理方式的基本概念。 所有 API 呼叫都必須使用簡單或授權的存取權 (定義如下)。 許多 API 方法都需要經過授權的存取權，但有些方法還是能使用。 有些 API 方法可能會使用不同行為 取決於您使用簡單或授權存取。 請參閱 API 的方法說明文件，判斷適當的存取權類型。

1. 簡易 API 存取 (API 金鑰)

這些 API 呼叫不會存取任何使用者私人資料。 您的應用程式必須驗證自身為符合下列條件的應用程式： 至 Google 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 金鑰，請按照下列步驟操作：

  1. 在 API 控制台中開啟「憑證」頁面。
  2. 這個 API 支援兩種憑證。 建立適用於您專案的憑證：

    • OAuth 2.0：每當應用程式要求私人使用者時 資料，必須在請求時一併傳送 OAuth 2.0 權杖。您的 應用程式會先將用戶端編號傳送給 取得權杖您可以為網路應用程式、服務帳戶或已安裝的應用程式產生 OAuth 2.0 憑證。

      詳情請參閱 OAuth 2.0 說明文件。

    • API 金鑰： 要求如果沒有提供 OAuth 2.0 權杖，就必須傳送 API 鍵。 金鑰可用來識別專案，並提供 API 存取權、配額與 報表。

      API 支援數種類型的 API 金鑰限制。若您的 API 金鑰 請先在控制台建立 API 金鑰，步驟如下： 按一下 [建立憑證]  >API 金鑰。您可以先限制金鑰，再使用 方法是按一下「Restrict key」(限制金鑰)，然後選取 限制。

為確保您 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，以及說明文件的連結。

您也可以使用 API Explorer 來瀏覽 API、列出可用方法，甚至嘗試從瀏覽器呼叫 API 呼叫。