Erste Schritte

Dieses Dokument enthält alle grundlegenden Informationen, die Sie für die Verwendung der Bibliothek benötigen. Er behandelt die Konzepte der Bibliotheken, enthält Beispiele für verschiedene Anwendungsfälle und enthält Links zu weiteren Informationen.

Einrichtung

Bevor Sie diese Bibliothek verwenden können, müssen Sie einige Einrichtungsschritte ausführen:

1. Wenn Sie noch kein Google-Konto haben, registrieren Sie sich.
2. Wenn Sie noch nie ein Projekt in der Google API Console erstellt haben, lesen Sie die Seite Projekte verwalten und erstellen Sie ein Projekt in der Google API Console.
3. Installieren Sie das NuGet-Paket, mit dem Sie arbeiten möchten.

Authentifizierung und Autorisierung

Es ist wichtig, die Grundlagen der API-Authentifizierung und -Autorisierung zu verstehen. Alle API-Aufrufe müssen entweder einen einfachen oder autorisierten Zugriff (gemäß nachstehender Definition) verwenden. Viele API-Methoden erfordern einen autorisierten Zugriff, einige können aber beide verwenden. Einige API-Methoden, die verwendet werden können, verhalten sich unterschiedlich, je nachdem, ob Sie einfachen oder autorisierten Zugriff verwenden. Informationen zum Ermitteln des geeigneten Zugriffstyps finden Sie in der Methodendokumentation der API.

1. Einfacher API-Zugriff (API-Schlüssel)

Diese API-Aufrufe greifen nicht auf private Nutzerdaten zu. Ihre Anwendung muss sich als eine Anwendung authentifizieren, die zu Ihrem Projekt in der Google API Console gehört. Dies ist erforderlich, um die Projektnutzung für Buchhaltungszwecke zu messen.

API-Schlüssel: Verwenden Sie zum Authentifizieren Ihrer Anwendung einen API-Schlüssel für Ihr API-Konsolenprojekt. Jeder einfache Zugriffsaufruf, den Ihre Anwendung durchführt, muss diesen Schlüssel enthalten.

Warnung: Halten Sie Ihren API-Schlüssel privat. Wenn jemand Ihren Schlüssel erhält, kann er damit Ihr Kontingent verbrauchen oder Ihr API-Konsolenprojekt in Rechnung stellen.

2. Autorisierter API-Zugriff (OAuth 2.0)

Diese API-Aufrufe greifen auf private Nutzerdaten zu. Bevor Sie sie aufrufen können, muss der Nutzer, der Zugriff auf die privaten Daten hat, Ihrer Anwendung Zugriff gewähren. Daher muss Ihre Anwendung authentifiziert sein, der Nutzer muss der Anwendung Zugriff gewähren und der Nutzer muss authentifiziert sein, um diesen Zugriff zu gewähren. Das erreichen Sie mit OAuth 2.0 und den dafür geschriebenen Bibliotheken.

Bereich: Jede API definiert einen oder mehrere Bereiche, die eine Reihe zulässiger Vorgänge deklarieren. Eine API kann beispielsweise schreibgeschützte und nicht schreibgeschützte Bereiche haben. Wenn Ihre Anwendung Zugriff auf Nutzerdaten anfordert, muss die Anfrage einen oder mehrere Bereiche enthalten. Der Nutzer muss den von der Anwendung angeforderten Zugriff genehmigen.

Aktualisierungs- und Zugriffstokens: Wenn ein Nutzer Ihrer Anwendung Zugriff gewährt, stellt der OAuth 2.0-Autorisierungsserver Ihrer Anwendung Aktualisierungs- und Zugriffstokens zur Verfügung. Diese Tokens sind nur für den angeforderten Bereich gültig. Ihre Anwendung verwendet Zugriffstokens, um API-Aufrufe zu autorisieren. Zugriffstokens laufen ab, Aktualisierungstokens jedoch nicht. Ihre Anwendung kann ein Aktualisierungstoken verwenden, um ein neues Zugriffstoken zu erhalten.

Warnung: Aktualisierungs- und Zugriffstokens müssen privat bleiben. Wenn jemand Ihre Tokens erhält, kann er damit auf private Nutzerdaten zugreifen.

Client-ID und Clientschlüssel: Diese Strings identifizieren Ihre Anwendung eindeutig und werden zum Abrufen von Tokens verwendet. Sie werden für Ihr Projekt in der API-Konsole erstellt. Es gibt drei Arten von Client-IDs. Achten Sie deshalb darauf, den richtigen Typ für Ihre Anwendung zu verwenden:

• Client-IDs für Webanwendungen
• Client-IDs der installierten Anwendung
• Dienstkonto-Client-IDs

Warnung: Halten Sie Ihren Clientschlüssel privat. Wenn jemand an Ihren Clientschlüssel gelangt, kann er damit Ihr Kontingent verbrauchen, Gebühren für Ihr Console-Projekt erheben und Zugriff auf Nutzerdaten anfordern.

Beispiele

In diesem Abschnitt finden Sie Beispiele für die einfache API-Verwendung ohne Autorisierung. Weitere Informationen zu Autorisierungsaufrufen finden Sie auf der OAuth 2.0-Seite für .NET.

Beispiel für eine einfache API

In diesem Beispiel wird der einfache API-Zugriff für eine Befehlszeilenanwendung verwendet. Sie ruft die Google Discovery API auf, um alle Google APIs aufzulisten.

Beispiel einrichten

Rufen Sie Ihren Simple API-Schlüssel ab. So finden Sie den API-Schlüssel Ihrer Anwendung:

1. Öffnen Sie die Seite „Anmeldedaten“ in der API Console.
2. Diese API unterstützt zwei Arten von Anmeldedaten. Erstellen Sie für Ihr Projekt geeignete Anmeldedaten:

   • OAuth 2.0: Wenn Ihre Anwendung private Nutzerdaten anfordert, muss sie zusammen mit der Anfrage ein OAuth 2.0-Token senden. Die Anwendung sendet zuerst eine Client-ID und möglicherweise einen Clientschlüssel, um ein Token zu erhalten. Sie können OAuth 2.0-Anmeldedaten für Webanwendungen, Dienstkonten oder installierte Anwendungen generieren.

     Weitere Informationen finden Sie in der OAuth 2.0-Dokumentation.

   • API-Schlüssel: Eine Anfrage, die kein OAuth 2.0-Token bereitstellt, muss einen API-Schlüssel senden. Mit diesem Schlüssel werden Ihr Projekt identifiziert sowie der API-Zugriff, das Kontingent und Berichte bereitgestellt.

     Die API unterstützt mehrere Arten von Einschränkungen für API-Schlüssel. Wenn der API-Schlüssel, den Sie benötigen, noch nicht vorhanden ist, müssen Sie ihn in der Console erstellen. Klicken Sie dazu auf Anmeldedaten erstellen > API-Schlüssel. Sie können Einschränkungen für den Schlüssel festlegen, bevor Sie ihn in der Produktion verwenden. Klicken Sie dazu auf Schlüssel einschränken und wählen Sie eine der Einschränkungen aus.

Folgen Sie zur Wahrung der Sicherheit Ihrer API-Schlüssel den Best Practices zur sicheren Verwendung von API-Schlüsseln.

Code zum Beispiel

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

Tipps zur Verwendung von API-Schlüsseln:

• Um einen bestimmten Dienst nutzen zu können, müssen Sie einen Verweis hinzufügen. Wenn Sie beispielsweise die Tasks API verwenden möchten, sollten Sie das zugehörige NuGet-Paket Google.Apis.Tasks.v1 installieren.
• Um eine Instanz eines Dienstes zu erstellen, rufen Sie einfach den zugehörigen Konstruktor auf. Beispiel: new TasksService(new BaseClientService.Initializer {...});".
• Alle Methoden eines Dienstes befinden sich in einzelnen Ressourcen im Dienstobjekt selbst. Der Erkennungsdienst hat eine Apis-Ressource, die eine List-Methode enthält. Wenn Sie service.Apis.List(..) aufrufen, wird ein Anfrageobjekt zurückgegeben, das auf diese Methode ausgerichtet ist.
  Rufen Sie zum Ausführen einer Anfrage die Methode Execute() oder ExecuteAsyc() in einer Anfrage auf.
• Legen Sie den API-Schlüssel mit dem Attribut ApiKey auf der Instanz BaseClientService.Initializer fest.

Informationen zu den APIs finden

Auf der Seite Unterstützte APIs werden alle APIs aufgeführt, auf die mit dieser Bibliothek zugegriffen werden kann, sowie Links zur Dokumentation.

Sie können auch den APIs Explorer verwenden, um APIs zu durchsuchen, verfügbare Methoden aufzulisten und sogar API-Aufrufe über Ihren Browser auszuprobieren.