このページは Cloud Translation API によって翻訳されました。

始める

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

セットアップ

このライブラリを使用するには、いくつかの設定手順を完了する必要があります。

Google アカウントをまだお持ちでない場合は、登録してください。
Google API Console プロジェクトを作成したことがない場合は、プロジェクトの管理ページを参照し、Google API Console でプロジェクトを作成します。
目的の 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 と、OAuth 用に記述されたライブラリによって実現されます。

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

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

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

ウェブアプリケーションのクライアント ID
インストール済みアプリケーションのクライアント ID
サービスアカウントのクライアント ID

例

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

シンプルな API の例

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

設定例

Simple API キーを取得するアプリの API キーを検索する方法は次のとおりです。

API コンソールで [認証情報] ページを開きます。
この 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 {...});"。
サービスのメソッドはすべて、サービスオブジェクト自体の個々のリソースに配置されます。Discovery サービスには、List メソッドを含む Apis リソースがあります。service.Apis.List(..) を呼び出すと、このメソッドを対象とするリクエストオブジェクトが返されます。
リクエストを実行するには、リクエストで Execute() または ExecuteAsyc() メソッドを呼び出します。
BaseClientService.Initializer インスタンスの ApiKey プロパティを使用して API キーを設定します。

API に関する情報の確認

サポートされている API ページには、このライブラリを使用してアクセスできるすべての API とドキュメントへのリンクが一覧表示されます。

また、API Explorer を使用して、API をブラウジングしたり、利用可能なメソッドをリストしたり、ブラウザからの API 呼び出しを試したりすることもできます。