スタートガイド

このドキュメントでは、ライブラリの使用を開始するために必要な基本情報をすべて提供します。ライブラリのコンセプト、さまざまなユースケースの例、詳細情報へのリンクが記載されています。

設定

このライブラリを使用するには、以下の設定手順を行う必要があります。

  1. Google アカウントをお持ちでない場合は、登録してください。
  2. Google API Console プロジェクトを作成したことがない場合は、プロジェクトの管理ページを読み、Google API Console でプロジェクトを作成します。
  3. 使用する NuGet パッケージをインストールします。

認証と認可

API の認証と認可の処理方法の基本を理解することが重要です。すべての API 呼び出しでは、シンプルなアクセスまたは承認済みのアクセス(以下に定義)を使用する必要があります。多くの API メソッドでは承認済みアクセスが必要ですが、そのどちらを使用しても構いません。どちらを使用できる API メソッドでも、シンプルアクセスと承認済みアクセスのどちらを使用するかによって動作が異なります。適切なアクセスタイプを決定するには、API のメソッドのドキュメントをご覧ください。

1. シンプルな API アクセス(API キー)

これらの API 呼び出しは、非公開のユーザーデータにはアクセスしません。アプリケーションは、Google API Console プロジェクトに属するアプリケーションとして自身を認証する必要があります。 これは、会計処理でプロジェクトの使用状況を測定するために必要です。

API キー: アプリケーションを認証するには、API Console プロジェクトの API キーを使用します。 アプリケーションが実行するすべての単純なアクセス呼び出しには、このキーが含まれている必要があります。

2. 承認済み API アクセス(OAuth 2.0)

これらの API 呼び出しは、非公開のユーザーデータにアクセスします。 これらを呼び出すには、限定公開データへのアクセス権を持つユーザーが、アプリにアクセス権を付与する必要があります。そのため、アプリは認証され、ユーザーはアプリにアクセス権を付与する必要があります。また、ユーザーがそのアクセス権を付与するには、認証を受ける必要があります。このすべては、OAuth 2.0 とそれに対応したライブラリによって実現されています。

スコープ: 各 API には、許可される一連のオペレーションを宣言する 1 つ以上のスコープを定義します。たとえば、API に読み取り専用と読み取り / 書き込みのスコープがあるとします。アプリケーションからユーザーデータへのアクセスをリクエストする場合は、リクエストに 1 つ以上のスコープを含める必要があります。ユーザーは、アプリケーションがリクエストしているアクセス スコープを承認する必要があります。

更新トークンとアクセス トークン: ユーザーがアプリケーションにアクセスを許可すると、OAuth 2.0 認可サーバーがアプリケーションに更新トークンとアクセス トークンを提供します。これらのトークンは、リクエストされたスコープに対してのみ有効です。アプリケーションは、アクセス トークンを使用して API 呼び出しを承認します。アクセス トークンには有効期限がありますが、更新トークンには有効期限がありません。アプリケーションは、更新トークンを使用して新しいアクセス トークンを取得できます。

クライアント ID とクライアント シークレット: アプリケーションを一意に識別する文字列。トークンの取得に使用されます。API Console でプロジェクト用に作成されます。クライアント ID には 3 つのタイプがあるため、アプリケーションに適したタイプを選択してください。

このセクションでは、認可を受けずに単純な API を使用する例を紹介します。認証呼び出しの詳細については、.NET の OAuth 2.0 ページをご覧ください。

シンプルな API の例

この例では、コマンドライン アプリケーションに対してシンプルな API アクセスを使用します。この関数は Google Discovery API を呼び出して、すべての Google API を一覧表示します。

設定例

Simple API キーを取得する。アプリケーションの API キーを確認する手順は次のとおりです。

  1. API コンソールで [認証情報] ページを開きます。
  2. この API は 2 種類の認証情報をサポートしています。 プロジェクトに適した認証情報を作成します。
    • 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 と、ドキュメントへのリンクが記載されています。

また、API Explorer を使用して、API を参照したり、使用可能なメソッドを一覧表示したり、ブラウザから API 呼び出しを試したりすることもできます。