Comenzar

En este documento, se proporciona toda la información básica que necesitas para comenzar a usar la biblioteca. Abarca los conceptos de la biblioteca, muestra ejemplos para varios casos prácticos y proporciona vínculos a más información.

Crear

Debes completar algunos pasos de configuración antes de usar esta biblioteca:

  1. Si aún no tienes una cuenta de Google, regístrate.
  2. Si nunca creaste un proyecto en la Consola de API de Google, lee la página Administra proyectos y crea un proyecto en la Consola de API de Google.
  3. Instala el paquete NuGet con el que deseas trabajar.

Autenticación y autorización

Es importante comprender los conceptos básicos sobre cómo se manejan la autorización y la autenticación de la API. Todas las llamadas a la API deben usar acceso simple o autorizado (definido a continuación). Muchos métodos de la API requieren acceso autorizado, pero algunos pueden usar cualquiera de ellos. Algunos métodos de API que pueden usar se comportan de manera diferente según si usas un acceso simple o autorizado. Consulta la documentación del método de la API para determinar el tipo de acceso adecuado.

1. Acceso simple a la API (claves de API)

Estas llamadas a la API no acceden a ningún dato privado del usuario. Tu aplicación debe autenticarse como una aplicación que pertenece a tu proyecto de la consola de la API de Google. Esto es necesario para medir el uso del proyecto con fines contables.

Clave de API: A fin de autenticar tu aplicación, usa una clave de API para tu proyecto de la Consola de API. Cada llamada de acceso simple que realice tu aplicación debe incluir esta clave.

2. Acceso autorizado a la API (OAuth 2.0)

Estas llamadas a la API acceden a los datos privados del usuario. Antes de que puedas llamarlos, el usuario que tiene acceso a los datos privados debe otorgarle acceso a tu aplicación. Por lo tanto, tu aplicación debe estar autenticada, el usuario debe otorgar acceso a ella y el usuario debe estar autenticado para poder otorgarlo. Todo esto se logra con OAuth 2.0 y bibliotecas escritas para ello.

Alcance: Cada API define uno o más alcances que declaran un conjunto de operaciones permitidas. Por ejemplo, una API puede tener permisos de solo lectura y de lectura y escritura. Cuando tu aplicación solicita acceso a los datos del usuario, la solicitud debe incluir uno o más permisos. El usuario debe aprobar el alcance del acceso que solicita tu aplicación.

Tokens de actualización y acceso: Cuando un usuario otorga acceso a tu aplicación, el servidor de autorización OAuth 2.0 le proporciona a tu aplicación tokens de actualización y de acceso. Estos tokens solo son válidos para el alcance solicitado. Tu aplicación usa tokens de acceso para autorizar llamadas a la API. Los tokens de acceso caducan, pero los tokens de actualización no. Tu aplicación puede usar un token de actualización para adquirir un nuevo token de acceso.

ID de cliente y secreto de cliente: Estas strings identifican de forma única tu aplicación y se usan para adquirir tokens. Se crean para tu proyecto en la Consola de API. Hay tres tipos de ID de cliente, así que asegúrate de obtener el tipo correcto para tu aplicación:

Ejemplos

En esta sección, hay ejemplos de uso simple de la API sin autorización. Para obtener más información sobre las llamadas de autorización, consulta la página de OAuth 2.0 para .NET.

Ejemplo de API simple

En este ejemplo, se usa un acceso simple a la API para una aplicación de línea de comandos. Llama a la API de Google Discovery para enumerar todas las API de Google.

Configuración, por ejemplo

Obtén tu clave de API simple. Para encontrar la clave de API de tu aplicación, haz lo siguiente:

  1. Abre la página Credenciales en la Consola de API.
  2. En esta API, se admiten dos tipos de credenciales. Crea las credenciales adecuadas para tu proyecto:
    • OAuth 2.0: Siempre que se soliciten datos privados del usuario, mediante tu aplicación se debe enviar un token OAuth 2.0 junto con la solicitud. En primer lugar, se envía un ID de cliente y, posiblemente, un secreto de cliente para obtener un token a través de la aplicación. Puedes generar credenciales OAuth 2.0 para aplicaciones web, cuentas de servicio o aplicaciones instaladas.

      Para obtener más información, consulta la documentación de OAuth 2.0.

    • Claves de API: Una solicitud que no proporciona un token de OAuth 2.0 debe enviar una clave de API. Con la clave de API, se identifica tu proyecto y se proporciona acceso a la API, la cuota y los informes.

      En la API, se admiten varios tipos de restricciones sobre las claves de API. Si la clave de API que necesitas ya no existe, crea una clave de API en Console; para ello, haz clic en Crear credenciales > Clave de API. Puedes restringir la clave antes de utilizarla en producción si haces clic en Restringir clave y seleccionas una de las Restricciones.

Para garantizar la seguridad de tus claves de API, sigue las prácticas recomendadas de uso seguro de las claves de API.

Código, por ejemplo

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);
                }
            }
        }
    }
}

Sugerencias para usar claves de API:

  • Para usar un servicio específico, debes agregarle una referencia. Por ejemplo, si deseas usar la API de Tasks, debes instalar su paquete NuGet Google.Apis.Tasks.v1.
  • Para crear una instancia de un servicio, simplemente llama a su constructor. Por ejemplo: new TasksService(new BaseClientService.Initializer {...});".
  • Todos los métodos de un servicio se encuentran en recursos individuales en el objeto de servicio. El servicio de descubrimiento tiene un recurso Apis, que contiene un método List. Cuando llamas a service.Apis.List(..), se muestra un objeto de solicitud orientado a este método.
    Para ejecutar una solicitud, llama al método Execute() o ExecuteAsyc() en una solicitud.
  • Configura la clave de API con la propiedad ApiKey en la instancia BaseClientService.Initializer.

Busca información sobre las API

En la página API compatibles, se enumeran todas las API a las que se puede acceder con esta biblioteca y vínculos a documentación.

También puedes usar el Explorador de API para explorar las API, enumerar los métodos disponibles y hasta probar las llamadas a la API desde tu navegador.