Inizia

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

Configurazione

Per poter utilizzare questa raccolta devi completare alcuni passaggi di configurazione:

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 Gestione dei progetti e crea un progetto nella console API di Google.
3. Installa il pacchetto NuGet con cui vuoi lavorare.

autentica e autorizza

È importante comprendere le nozioni di base relative alla gestione dell'autenticazione e dell'autorizzazione delle 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 API che possono utilizzare si comportano in modo diverso a seconda che utilizzi un accesso semplice o autorizzato. Consulta la documentazione relativa al metodo dell'API per determinare il tipo di accesso appropriato.

1. Accesso semplice all'API (chiavi API)

Queste chiamate API non accedono ai dati privati dell'utente. L'applicazione deve autenticarsi come applicazione appartenente al progetto della console API di Google. Questa operazione è necessaria per misurare l'utilizzo del progetto a fini contabili.

Chiave API: per autenticare l'applicazione, utilizza una chiave API per il tuo progetto nella console API. Ogni semplice chiamata di accesso effettuata dall'applicazione deve includere questa chiave.

Avviso: mantieni privata la chiave API. Se qualcuno ottiene la tua chiave, potrebbe utilizzarla per consumare la tua quota o comportare addebiti per il tuo progetto della console API.

2. Accesso API autorizzato (OAuth 2.0)

Queste chiamate API accedono a dati privati dell'utente. Prima di poterli chiamare, l'utente che ha accesso ai dati privati deve concedere l'accesso alla tua applicazione. Di conseguenza, l'applicazione deve essere autenticata, l'utente deve concedere l'accesso per l'applicazione e l'utente deve essere autenticato per concedere questo accesso. Tutto questo grazie a OAuth 2.0 e alle librerie scritte appositamente 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 lettura-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 dall'applicazione.

Token di aggiornamento e di accesso: quando un utente concede l'accesso all'applicazione, il server di autorizzazione OAuth 2.0 fornisce all'applicazione i token di aggiornamento e accesso. Questi token sono validi solo per l'ambito richiesto. L'applicazione utilizza i token di accesso per autorizzare le chiamate API. I token di accesso hanno una scadenza, ma non quelli di aggiornamento. L'applicazione può utilizzare un token di aggiornamento per acquisire un nuovo token di accesso.

Avviso: mantieni privati i token di aggiornamento e di accesso. Se qualcuno ottiene i tuoi token, potrebbe utilizzarli per accedere ai dati privati dell'utente.

ID client e client secret: queste stringhe identificano in modo univoco l'applicazione e vengono utilizzate per acquisire token. Vengono creati per il tuo progetto nella console API. Esistono tre tipi di ID client, pertanto assicurati di scegliere quello corretto per la tua applicazione:

• ID client di applicazioni web
• ID client applicazione installata
• ID client account di servizio

Avviso: mantieni privato il client secret. Se qualcuno ottiene il tuo client secret, potrebbe utilizzarlo per usufruire della tua quota, comportare addebiti per il tuo progetto della console e richiedere l'accesso ai dati utente.

Esempi

In questa sezione sono disponibili esempi di semplice utilizzo dell'API senza autorizzazione. Per maggiori informazioni sulle chiamate di autorizzazione, consulta la pagina OAuth 2.0 per .NET.

Esempio di API semplice

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

Configurazione, ad esempio

Procurati la chiave API semplice. Per trovare la chiave API dell'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 la tua applicazione richiede dati privati dell'utente, deve inviare un token OAuth 2.0 insieme alla richiesta. L'applicazione invia innanzitutto un ID client e, possibilmente, un client secret per ottenere un token. Puoi generare credenziali OAuth 2.0 per applicazioni web, account di servizio o applicazioni installate.

     Per ulteriori informazioni, 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 API, quota e report.

     L'API supporta diversi tipi di limitazioni per le chiavi API. Se la chiave API necessaria non esiste già, creane una 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, ad 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 delle chiavi API:

• Per utilizzare un servizio specifico, devi aggiungere un riferimento al servizio. Ad esempio, se vuoi utilizzare l'API Tasks, devi installare il relativo pacchetto NuGet Google.Apis.Tasks.v1.
• Per creare un'istanza di un servizio, è sufficiente chiamare il suo costruttore. Ad esempio: new TasksService(new BaseClientService.Initializer {...});".
• Tutti i metodi di un servizio si trovano su singole risorse nell'oggetto di servizio stesso. Il servizio di rilevamento ha una risorsa Apis, che contiene un metodo List. Quando chiami service.Apis.List(..), viene restituito questo metodo come target di un oggetto di richiesta.
  Per eseguire una richiesta, chiama il metodo Execute() o ExecuteAsyc() su una richiesta.
• 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 utilizzando questa libreria, nonché i link alla documentazione.

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