Per iniziare

Questo documento fornisce tutte le informazioni di base necessarie per iniziare a utilizzare la libreria. Include i concetti della libreria, mostra esempi per vari casi d'uso e fornisce link a ulteriori informazioni.

Configurazione

Sono necessari alcuni passaggi di configurazione prima di poter utilizzare questa libreria:

  1. Se non hai ancora un Account Google, registrati.
  2. Se non hai mai creato un progetto nella console API di Google, leggi la pagina di gestione dei progetti e crea un progetto nella console API di Google.
  3. Installa il pacchetto NuGet con cui vuoi lavorare.

Autenticazione e autorizzazione

È importante comprendere le nozioni di base su come vengono gestite l'autenticazione e l'autorizzazione dell'API. Tutte le chiamate API devono utilizzare l'accesso semplice o autorizzato (definito di seguito). Molti metodi API richiedono l'accesso autorizzato, ma alcuni possono utilizzare entrambi. Alcuni metodi delle API che possono utilizzare un comportamento diverso variano a seconda che si utilizzi un accesso semplice o autorizzato. Consulta la documentazione sul metodo dell'API per determinare il tipo di accesso appropriato.

1. Accesso API semplice (chiavi API)

Queste chiamate API non accedono ad alcun dato utente privato. L'applicazione deve autenticarsi come un'applicazione appartenente al tuo progetto Google API Console. Questo è necessario per misurare l'utilizzo del progetto a fini contabili.

Chiave API: per autenticare la tua applicazione, utilizza una chiave API per il progetto API Console. Ogni semplice chiamata di accesso effettuata dalla tua applicazione deve includere questa chiave.

2. Accesso API autorizzato (OAuth 2.0)

Queste chiamate API accedono ai dati utente privati. Prima di chiamare i tuoi utenti, l'utente che ha accesso ai dati privati deve concedere l'accesso alla tua applicazione. Pertanto, l'applicazione deve essere autenticata, l'utente deve concedere l'accesso per la tua applicazione e l'utente deve essere autenticato per concedere tale accesso. Tutto ciò si ottiene con OAuth 2.0 e librerie scritte per questo.

Ambito: ogni API definisce uno o più ambiti che dichiarano un insieme di operazioni consentite. Ad esempio, un'API potrebbe avere ambiti di sola lettura e di scrittura. Quando la tua applicazione richiede l'accesso ai dati utente, la richiesta deve includere uno o più ambiti. L'utente deve approvare l'ambito di accesso richiesto dalla tua applicazione.

Token di aggiornamento e accesso: quando un utente concede l'accesso all'applicazione, il server di autorizzazione OAuth 2.0 fornisce all'applicazione token di aggiornamento e di accesso. Questi token sono validi solo per l'ambito richiesto. La tua applicazione utilizza token di accesso per autorizzare le chiamate API. I token di accesso scadono, al contrario dei token di aggiornamento. La tua applicazione può utilizzare un token di aggiornamento per acquisire un nuovo token di accesso.

Client-ID e client secret: queste stringhe identificano in modo univoco la tua applicazione e vengono utilizzate per acquisire i token. Vengono create per il tuo progetto nella Console API. Esistono tre tipi di ID client, quindi assicurati di ottenere il tipo corretto per la tua applicazione:

Esempi

In questa sezione vengono riportati alcuni esempi di utilizzo semplice delle API senza autorizzazione. Per ulteriori informazioni sulle chiamate di autorizzazione, consulta la pagina OAuth 2.0 per .NET.

Esempio di API semplice

Questo esempio utilizza un semplice accesso API per un'applicazione a riga di comando. Chiama l'API Google Discovery per elencare tutte le API di Google.

Configura, ad esempio

Procurati la chiave API semplice. Per trovare la chiave API della tua applicazione:

  1. Apri la pagina Credenziali nella console API.
  2. Questa API supporta due tipi di credenziali. Crea le credenziali appropriate per il tuo progetto:

    • OAuth 2.0: ogni volta che l'applicazione richiede dati utente privati, deve inviare un token OAuth 2.0 insieme alla richiesta. L'applicazione invia prima un ID client e, eventualmente, un client secret per ottenere un token. Puoi generare le credenziali OAuth 2.0 per applicazioni web, account di servizio o applicazioni installate.

      Per scoprire di più, consulta la documentazione relativa a OAuth 2.0.

    • Chiavi API: Una richiesta che non fornisce un token OAuth 2.0 deve inviare una chiave API. La chiave identifica il progetto e fornisce accesso, quota e rapporti API.

      L'API supporta diversi tipi di restrizioni sulle chiavi API. Se la chiave API di cui hai bisogno non esiste già, crea una chiave API nella console facendo clic su Crea credenziali > Chiave API. Puoi limitare la chiave prima di utilizzarla in produzione facendo clic su Limita chiave e selezionando una delle Restrizioni.

Per proteggere le tue chiavi API, segui le best practice per l'utilizzo sicuro delle chiavi API.

Codice di esempio

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

Suggerimenti per l'utilizzo di chiavi API:

  • Per utilizzare un servizio specifico, devi aggiungere un riferimento al servizio. Ad esempio, se vuoi utilizzare l'API Tasks, devi installare il pacchetto NuGet Google.Apis.Tasks.v1.
  • Per creare un'istanza di un servizio, chiama semplicemente il relativo costruttore. Ad esempio: new TasksService(new BaseClientService.Initializer {...});".
  • Tutti i metodi di un servizio si trovano su singole risorse nell'oggetto del servizio stesso. Il servizio Discovery ha una risorsa Apis, che contiene un metodo List. Quando chiami service.Apis.List(..), viene restituito un oggetto richiesta che ha come target questo metodo.
    Per eseguire una richiesta, chiama il metodo Execute() o ExecuteAsyc() al suo interno.
  • Imposta la chiave API utilizzando la proprietà ApiKey nell'istanza BaseClientService.Initializer.

Trovare informazioni sulle API

Nella pagina API supportate sono elencate tutte le API a cui è possibile accedere usando questa libreria, oltre ai link alla documentazione.

Puoi anche utilizzare Explorer API per sfogliare le API, elencare i metodi disponibili e perfino provare le chiamate API dal tuo browser.