Commencer

Ce document fournit toutes les informations de base dont vous avez besoin pour commencer à utiliser la bibliothèque. Il aborde les concepts de la bibliothèque, présente des exemples pour différents cas d'utilisation et fournit des liens vers plus d'informations.

Prérequis

Avant de pouvoir utiliser cette bibliothèque, vous devez suivre quelques étapes de configuration:

  1. Si vous ne possédez pas encore de compte Google, inscrivez-vous.
  2. Si vous n'avez jamais créé de projet dans la console Google APIs, lisez la page Gérer les projets et créez-en un dans la console Google APIs.
  3. Installez le package NuGet que vous souhaitez utiliser.

Authentification et autorisation

Il est important de comprendre les bases de la gestion de l'authentification et de l'autorisation des API. Tous les appels d'API doivent utiliser un accès simple ou autorisé (défini ci-dessous). De nombreuses méthodes d'API nécessitent un accès autorisé, mais certaines peuvent utiliser l'une ou l'autre de ces méthodes. Certaines méthodes d'API qui peuvent utiliser l'une ou l'autre se comportent différemment, selon que vous utilisez un accès simple ou autorisé. Consultez la documentation de la méthode de l'API pour déterminer le type d'accès approprié.

1. Accès à l'API simple (clés API)

Ces appels d'API n'accèdent à aucune donnée utilisateur privée. Votre application doit s'authentifier en tant qu'application appartenant à votre projet dans la console Google APIs. Cela est nécessaire pour mesurer l'utilisation du projet à des fins comptables.

Clé API : pour authentifier votre application, utilisez une clé API pour votre projet dans la console API. Chaque appel d'accès simple effectué par votre application doit inclure cette clé.

2. Accès aux API autorisées (OAuth 2.0)

Ces appels d'API accèdent à des données utilisateur privées. Pour que vous puissiez les appeler, l'utilisateur ayant accès aux données privées doit accorder l'accès à votre application. Par conséquent, votre application doit être authentifiée, l'utilisateur doit accorder l'accès à votre application et l'utilisateur doit être authentifié pour accorder cet accès. Tout cela est possible avec OAuth 2.0 et les bibliothèques associées.

Champ d'application : chaque API définit un ou plusieurs champs d'application qui déclarent un ensemble d'opérations autorisées. Par exemple, une API peut avoir des niveaux d'accès en lecture seule et en lecture-écriture. Lorsque votre application demande l'accès aux données utilisateur, la requête doit inclure un ou plusieurs champs d'application. L'utilisateur doit approuver le niveau d'accès demandé par votre application.

Jetons d'actualisation et jetons d'accès : lorsqu'un utilisateur autorise l'accès à votre application, le serveur d'autorisation OAuth 2.0 fournit à celle-ci des jetons d'actualisation et d'accès. Ces jetons ne sont valides que pour le champ d'application demandé. Votre application utilise des jetons d'accès pour autoriser les appels d'API. Les jetons d'accès ont une date d'expiration, mais pas les jetons d'actualisation. Votre application peut utiliser un jeton d'actualisation pour acquérir un nouveau jeton d'accès.

ID client et code secret du client : ces chaînes identifient de manière unique votre application et sont utilisées pour acquérir des jetons. Ils sont créés pour votre projet dans la console API. Il existe trois types d'ID client. Assurez-vous donc d'obtenir le type approprié pour votre application:

Exemples

Cette section présente des exemples d'utilisation simple d'API sans autorisation. Pour en savoir plus sur les appels d'autorisation, consultez la page OAuth 2.0 pour .NET.

Exemple d'API simple

Cet exemple utilise un accès simple à l'API pour une application de ligne de commande. Elle appelle l'API Google Discovery pour répertorier toutes les API Google.

Exemple de configuration

Obtenez votre clé API simple. Pour trouver la clé API de votre application, procédez comme suit:

  1. Ouvrez la page Identifiants dans la console API.
  2. Deux types d'identifiants sont disponibles pour cette API. Créez les identifiants adaptés à votre projet :
    • OAuth 2.0 : chaque fois que votre application demande des données utilisateur privées, elle doit envoyer un jeton OAuth 2.0 en même temps que la requête. Votre application envoie d'abord un identifiant client, puis éventuellement un code secret du client pour obtenir un jeton. Vous pouvez générer des identifiants OAuth 2.0 pour des applications Web, des comptes de service ou des applications installées.

      Pour en savoir plus, consultez la documentation OAuth 2.0.

    • Clés API : une demande qui ne fournit pas de jeton OAuth 2.0 doit envoyer une clé API. Cette clé identifie votre projet et vous donne accès à l'API, aux quotas et aux rapports.

      L'API propose plusieurs types de restrictions applicables aux clés API. Si la clé API dont vous avez besoin n'existe pas déjà, créez-en une dans la console en cliquant sur Créer des identifiants  > Clé API. Vous pouvez restreindre la clé avant de l'utiliser en production en cliquant sur Restreindre la clé et en sélectionnant l'une des restrictions.

Pour sécuriser vos clés API, suivez les Bonnes pratiques pour utiliser des clés API en toute sécurité.

Exemple de code

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

Conseils pour l'utilisation des clés API:

  • Pour utiliser un service spécifique, vous devez lui ajouter une référence. Par exemple, si vous souhaitez utiliser l'API Tasks, vous devez installer son package NuGet, Google.Apis.Tasks.v1.
  • Pour créer une instance de service, il vous suffit d'appeler son constructeur. Exemple : new TasksService(new BaseClientService.Initializer {...});".
  • Toutes les méthodes d'un service sont situées sur des ressources individuelles dans l'objet de service lui-même. Le service de découverte dispose d'une ressource Apis, qui contient une méthode List. Lorsque vous appelez service.Apis.List(..), un objet de requête ciblant cette méthode est renvoyé.
    Pour exécuter une requête, appelez la méthode Execute() ou ExecuteAsyc() sur une requête.
  • Définissez la clé API à l'aide de la propriété ApiKey sur l'instance BaseClientService.Initializer.

Obtenir des informations sur les API

La page API compatibles répertorie toutes les API accessibles à l'aide de cette bibliothèque, ainsi que des liens vers la documentation.

Vous pouvez également utiliser APIs Explorer pour parcourir les API, répertorier les méthodes disponibles et même essayer des appels d'API depuis votre navigateur.