Dieses Dokument enthält alle grundlegenden Informationen, die Sie für die Verwendung der Bibliothek benötigen. Darin werden Konzepte der Bibliothek behandelt, Beispiele für verschiedene Anwendungsfälle angezeigt und Links zu weiteren Informationen bereitgestellt.
Einrichtung
Bevor Sie diese Bibliothek verwenden können, müssen Sie einige Einrichtungsschritte ausführen:
- Wenn Sie noch kein Google-Konto haben, registrieren Sie sich hier.
- Wenn du noch kein Google API Console-Projekt erstellt hast, lies die Seite Projekte verwalten und erstelle ein Projekt in der Google API Console.
- Installieren Sie das NuGet-Paket, das Sie verwenden 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 haben (siehe unten). Viele API-Methoden erfordern einen autorisierten Zugriff. Einige können beide verwenden. Einige API-Methoden, die sich entweder verwenden lassen, verhalten sich je nachdem, ob Sie einfachen oder autorisierten Zugriff verwenden. Informationen zum Ermitteln des entsprechenden Zugriffstyps finden Sie in der Dokumentation zur Methode der API.
1. Einfacher API-Zugriff (API-Schlüssel)
Diese API-Aufrufe greifen nicht auf private Nutzerdaten zu. Die Anwendung muss sich selbst als Anwendung authentifizieren, die zu Ihrem Google API Console-Projekt gehört. Dies ist erforderlich, um die Projektnutzung zu Buchhaltungszwecken zu messen.
API-Schlüssel: Verwende zur Authentifizierung deiner Anwendung einen API-Schlüssel für dein API-Konsolenprojekt. Jeder einfache Zugriff, den Ihre Anwendung ausführt, muss diesen Schlüssel enthalten.
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 Zugriff für die Anwendung gewähren und der Nutzer muss authentifiziert sein, um diesen Zugriff zu gewähren. Dies erreichen Sie mit OAuth 2.0 und dafür erstellten Bibliotheken.
Bereich: Jede API definiert einen oder mehrere Bereiche, die eine Reihe von zulässigen Vorgängen deklarieren. Eine API kann beispielsweise schreibgeschützte und Lese-/Schreibbereiche haben. Wenn Ihre Anwendung Zugriff auf Nutzerdaten anfordert, muss die Anfrage einen oder mehrere Bereiche enthalten. Der Nutzer muss den vom Nutzer angeforderten Zugriffsbereich genehmigen.
Aktualisierungs- und Zugriffstokens: Wenn ein Nutzer Ihrer Anwendung Zugriff gewährt, sendet der OAuth 2.0-Autorisierungsserver Ihrer Anwendung Aktualisierungs- und Zugriffstokens. Diese Tokens sind nur für den angeforderten Bereich gültig. Ihre Anwendung verwendet Zugriffstokens zur Autorisierung von API-Aufrufen. Zugriffstokens laufen ab, Aktualisierungstokens jedoch nicht. Ihre Anwendung kann ein Aktualisierungstoken verwenden, um ein neues Zugriffstoken zu erhalten.
Client-ID und Clientschlüssel: Diese Strings identifizieren Ihre Anwendung eindeutig und werden zum Abrufen von Tokens verwendet. Sie werden in der API Console für Ihr Projekt erstellt. Es gibt drei Arten von Client-IDs. Achte darauf, den richtigen Typ für deine Anwendung zu ermitteln:
- Client-IDs von Webanwendungen
- Client-IDs von installierten Anwendungen
- Client-IDs von Dienstkonten
Beispiele
In diesem Abschnitt finden Sie Beispiele für die einfache API-Nutzung ohne Autorisierung. Weitere Informationen zu Autorisierungsaufrufen finden Sie auf der OAuth 2.0-Seite für .NET.
Einfaches API-Beispiel
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.
Einrichtung, z. B.
Rufen Sie Ihren Simple API-Schlüssel ab. So finden Sie den API-Schlüssel Ihrer Anwendung:
- Öffnen Sie in der API Console die Seite „Anmeldedaten“.
-
Diese API unterstützt zwei Arten von Anmeldedaten.
Erstellen Sie die Anmeldedaten, die für Ihr Projekt geeignet sind:
-
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 erforderliche API-Schlüssel noch nicht vorhanden ist, erstellen Sie einen API-Schlüssel in der Console, indem Sie auf Anmeldedaten erstellen > API-Schlüssel klicken. Sie können den Schlüssel einschränken, bevor Sie ihn in der Produktionsumgebung 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, z. B.
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:
- Wenn Sie einen bestimmten Dienst nutzen möchten, 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.
- Rufen Sie einfach den zugehörigen Konstruktor auf, um eine Instanz eines Dienstes zu erstellen. Beispiel:
new TasksService(new BaseClientService.Initializer {...});"
. - Alle Methoden eines Dienstes befinden sich in einzelnen Ressourcen des Dienstobjekts selbst.
Der Discovery-Dienst hat eine
Apis
-Ressource, die eineList
-Methode enthält. Wenn Sieservice.Apis.List(..)
aufrufen, wird ein Anfrageobjekt zurückgegeben, das auf diese Methode ausgerichtet ist.
Rufen Sie zum Ausführen einer Anfrage die MethodeExecute()
oderExecuteAsyc()
für eine Anfrage auf. - Legen Sie den API-Schlüssel mit dem Attribut
ApiKey
auf der InstanzBaseClientService.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 in Ihrem Browser auszuprobieren.