Commencer

Ce document fournit toutes les informations de base dont vous avez besoin pour commencer à utiliser la bibliothèque. Il couvre les concepts de la bibliothèque, propose des exemples pour divers cas d'utilisation et fournit des liens vers plus d'informations.

Configuration

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

  1. Si vous n'avez pas encore de compte Google, inscrivez-vous.
  2. Si vous n'avez jamais créé de projet dans la console Google APIs, consultez la page Gérer des 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 principes de base 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 requièrent un accès autorisé, mais certaines peuvent utiliser l'une ou l'autre. Certaines méthodes d'API peuvent se comporter différemment selon que vous utilisez un accès simple ou autorisé. Consultez la documentation sur la méthode d'API pour déterminer le type d'accès approprié.

1. Accès simple à l'API (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 à l'API autorisé (OAuth 2.0)

Ces appels d'API accèdent aux données utilisateur privées. Pour que vous puissiez les appeler, l'utilisateur qui a accès aux données privées doit accorder l'accès à votre application. Par conséquent, votre application doit être authentifiée, et l'utilisateur doit lui accorder l'accès, lequel doit également être authentifié. Tout cela est réalisé à l'aide du protocole OAuth 2.0 et des bibliothèques correspondantes.

Champ d'application : chaque API définit un ou plusieurs champs d'application qui déclarent un ensemble d'opérations autorisé. 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, elle doit inclure un ou plusieurs champs d'application. L'utilisateur doit approuver le champ d'application de votre demande.

Jetons d'actualisation et d'accès : lorsqu'un utilisateur accorde l'accès à votre application, le serveur d'autorisation OAuth 2.0 fournit à votre application 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 expirent, 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 servent à acquérir des jetons. Ils sont créés pour votre projet dans la console API. Il existe trois types d'ID client. Veillez donc à choisir le type approprié pour votre application:

Exemples

Cette section contient 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 API simple pour une application de ligne de commande. Elle appelle l'API Google Discovery pour obtenir la liste de toutes les API Google.

Configuration par exemple

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 une clé API 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é.

Code, par exemple

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 d'utilisation des clés API:

  • Pour utiliser un service spécifique, vous devez y 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 d'un 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 l'explorateur d'API pour parcourir les API, répertorier les méthodes disponibles et même essayer les appels d'API à partir de votre navigateur.