开始使用

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

初始设置

您需要先完成一些设置步骤,然后才能使用此库:

  1. 如果您还没有 Google 帐号,请注册
  2. 如果您从未创建过 Google API 控制台项目,请阅读“管理项目”页面,并在 Google API 控制台中创建一个项目。
  3. 安装您要使用的 NuGet 软件包。

身份验证与授权

了解有关如何处理 API 身份验证和授权的基础知识非常重要。所有 API 调用都必须使用简单访问或授权访问(定义见下文)。许多 API 方法都需要经过授权的访问,但有些 API 方法可以使用。一些 API 方法可以使用上述两种方法之一,具体取决于您是使用简单访问还是授权访问。请参阅 API 的方法文档以确定适当的访问权限类型。

1. 简单的 API 访问(API 密钥)

这些 API 调用不会访问任何用户私人数据。您的应用必须验证自身的身份,确认该应用属于您的 Google API 控制台项目。 出于核算目的衡量项目使用情况时需要此 ID。

API 密钥:如需对应用进行身份验证,请为您的 API 控制台项目使用 API 密钥。 您的应用进行的每个简单的访问调用都必须包含此密钥。

2. 已获授权的 API 访问权限 (OAuth 2.0)

这些 API 调用会访问用户私人数据。在调用它们之前,有权访问私有数据的用户必须向您的应用授予访问权限。因此,您的应用必须经过身份验证,用户必须为应用授予访问权限,并且用户必须经过身份验证才能授予该访问权限。这一切都是通过 OAuth 2.0 以及为其编写的库完成的。

范围:每个 API 均定义一个或多个范围,用于声明一组允许的操作。例如,API 可能具有只读和读写范围。当您的应用请求访问用户数据时,该请求必须包含一个或多个范围。用户需要批准您的应用所请求的访问权限范围。

刷新和访问令牌:当用户向您的应用授予访问权限时,OAuth 2.0 授权服务器会为您的应用提供刷新令牌和访问令牌。这些令牌仅在所请求的范围有效。您的应用使用访问令牌为 API 调用授权。 访问令牌会过期,但刷新令牌不会。 您的应用可以使用刷新令牌来获取新的访问令牌。

客户端 ID 和客户端密钥:这些字符串可唯一标识您的应用并用于获取令牌。系统会在 API 控制台上为您的项目创建这些 API。客户端 ID 有三种类型,因此请务必获取适用于您的应用的正确类型:

示例

本部分将提供一些未经授权使用简单 API 的示例。如需详细了解授权调用,请参阅 .NET 的 OAuth 2.0 页面

简单的 API 示例

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

设置示例

获取您的简单 API 密钥。如需查找您应用的 API 密钥,请执行以下操作:

  1. 打开 API 控制台中的“凭据”页面
  2. 此 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 {...});"
  • 服务的所有方法都位于服务对象本身的各个资源上。发现服务具有 Apis 资源,其中包含 List 方法。当您调用 service.Apis.List(..) 时,系统会返回一个定位此方法的请求对象。
    如需执行请求,请对请求调用 Execute()ExecuteAsyc() 方法。
  • 使用 BaseClientService.Initializer 实例上的 ApiKey 属性设置 API 密钥。

查找有关 API 的信息

支持的 API 页面列出了可以使用此库访问的所有 API,以及指向相关文档的链接。

您还可以使用 API Explorer 来浏览 API、列出可用方法,甚至尝试通过浏览器进行 API 调用。