此页面由 Cloud Translation API 翻译。

开始使用

本文档提供了开始使用该库所需的所有基本信息。其中介绍了库概念显示了各种应用场景的示例并提供指向更多信息的链接。

设置

使用此库之前，您需要完成一些设置步骤：

如果您还没有 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 有三种类型，因此请务必获取正确的应用类型：

Web 应用客户端 ID
已安装的应用客户端 ID
服务账号客户端 ID

。 <ph type="x-smartling-placeholder">

示例

本部分将提供一些无需授权的简单 API 使用示例。有关授权调用的详细信息，请参阅 .NET 的 OAuth 2.0 页面。

简单的 API 示例

此示例对命令行应用使用简单的 API 访问。它会调用 Google Discovery API 可列出所有 Google API。

示例设置

获取简易 API 密钥。如需查找应用的 API 密钥，请执行以下操作：

打开 API 控制台中的“凭据”页面。
此 API 支持两种类型的凭据。创建适合您项目的凭据： <ph type="x-smartling-placeholder">
- 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 密钥的安全，请遵循以安全的方式使用 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 调用。