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 de distintos casos de uso, y proporciona vínculos para obtener más información.

Configuración

Para poder usar esta biblioteca, debes completar algunos pasos de configuración:

  1. Si aún no tienes una cuenta de Google, registrarse.
  2. Si nunca creaste un proyecto de la Consola de APIs de Google, lee el Página de administración de proyectos y crear un proyecto en la Consola de APIs de Google.
  3. Instala el paquete NuGet con el que deseas trabajar.

Autenticación y autorización

Es importante comprender los conceptos básicos de cómo se manejan la autenticación y la 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 ellas. Algunos métodos de API que pueden usar cualquiera de ellas se comportan de manera diferente según si usa 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 a sí misma como una aplicación que pertenece a tu proyecto de la Consola de APIs de Google. Esto es necesario para medir el uso del proyecto con fines contables.

Clave de API: Para autenticar tu aplicación, usa un Clave de API para tu proyecto de la Consola de APIs. Cada llamada de acceso simple que realiza tu aplicación debe incluir esta clave.

2. Acceso autorizado a la API (OAuth 2.0)

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

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 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 acceso y actualización: Cuando un usuario otorga acceso a tu aplicación, el servidor de autorización OAuth 2.0 le proporciona a la aplicación tokens de acceso y actualización. Estos tokens solo son válidos para el permiso solicitado. Tu aplicación usa tokens de acceso para autorizar llamadas a la API. Los tokens de acceso vencen, pero los de actualización no. Tu aplicación puede usar un token de actualización para adquirir un token de acceso nuevo.

ID de cliente y secreto del cliente: Estas cadenas identifican de manera inequívoca tu aplicación y se usan para adquirir tokens. Se crean para tu proyecto en la Consola de APIs. Existen tres tipos de IDs de cliente: así que asegúrate de obtener el tipo correcto para tu aplicación:

Ejemplos

En esta sección, hay ejemplos del uso simple de la API sin autorización. Para obtener más información sobre las llamadas de autorización, consulta el 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 al 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 APIs.
  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 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 no existe, crea una clave de API en la consola 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 claves de API:

  • Para usar un servicio específico, debes agregarle una referencia. Por ejemplo, si quieres usar API de Tasks, deberías instalar el 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 ubican en recursos individuales dentro 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 orientado 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

El APIs admitidas enumera todas las APIs a las que se puede acceder con esta biblioteca, así como vínculos a la documentación.

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