Comenzar

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

Configuración

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

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

Autenticación y autorización

Es importante comprender los conceptos básicos de la forma en que se manejan la autenticación y autorización de las APIs. Todas las llamadas a la API deben usar un acceso simple o autorizado (definido a continuación). Muchos métodos de API requieren acceso autorizado, pero algunos pueden usar cualquiera de ellos. Algunos métodos de la API que pueden usar cualquiera de los dos se comportan de manera diferente según si utilizas el 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 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, utiliza una clave de API para el proyecto de la Consola de API. Cada llamada de acceso simple que realiza tu aplicación debe incluir esta clave.

2. Acceso a la API autorizada (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 otorgar acceso a tu aplicación. Por lo tanto, tu aplicación se debe autenticar, el usuario debe otorgar acceso a la aplicación y el usuario debe estar autenticado para otorgar ese acceso. Todo esto se logra con OAuth 2.0 y las 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 alcances de solo lectura y alcance 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 permiso de 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 de OAuth 2.0 le proporciona tokens de actualización y de acceso a tu aplicación. 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 de actualización no. Tu aplicación puede usar un token de actualización para adquirir un nuevo token de acceso.

ID 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. Existen 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 APIs de Google.

Configuración de 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 apropiadas 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 aún no existe, crea una en la consola. Para ello, haz clic en Crear credenciales > Clave de API. Puedes restringir la clave antes de usarla en producción. Para ello, haz clic en Restringir clave y selecciona 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 las 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, solo debes llamar a su constructor. Por ejemplo: new TasksService(new BaseClientService.Initializer {...});".
  • Todos los métodos de un servicio se ubican en recursos individuales del 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 que se orienta a este método.
    Para ejecutar una solicitud, llama al método Execute() o ExecuteAsyc() en ella.
  • Configura la clave de API con la propiedad ApiKey en la instancia BaseClientService.Initializer.

Encuentra información sobre las APIs

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

También puedes usar el Explorador de API para explorar las APIs, hacer una lista de los métodos disponibles o incluso probar las llamadas a la API desde tu navegador.