Rozpocznij

Ten dokument zawiera wszystkie podstawowe informacje potrzebne do rozpoczęcia korzystania z biblioteki. Obejmuje on zagadnienia związane z biblioteką, przykłady różnych zastosowań i linki do dodatkowych informacji.

Konfiguracja

Zanim zaczniesz korzystać z tej biblioteki, musisz wykonać kilka czynności konfiguracyjnych:

  1. Jeśli nie masz jeszcze konta Google, zarejestruj się.
  2. Jeśli nie masz jeszcze utworzonego projektu w Konsoli interfejsów API Google, przeczytaj stronę Zarządzanie projektami i utwórz projekt w Konsoli interfejsów API Google.
  3. Zainstaluj pakiet NuGet, z którym chcesz pracować.

Uwierzytelnianie i autoryzacja

Warto znać podstawy obsługi uwierzytelniania i autoryzacji w interfejsie API. Wszystkie wywołania interfejsu API muszą korzystać z dostępu prostego lub autoryzowanego dostępu (zdefiniowanego poniżej). Wiele metod interfejsu API wymaga autoryzowanego dostępu, ale niektóre mogą z niego korzystać. Niektóre metody interfejsu API, które mogą działać inaczej, w zależności od tego, czy korzystasz z dostępu prostego, czy autoryzowanego dostępu. Aby określić odpowiedni typ dostępu, zapoznaj się z dokumentacją metod interfejsu API.

1. Prosty dostęp do interfejsu API (klucze interfejsu API)

Te wywołania interfejsu API nie mają dostępu do żadnych prywatnych danych użytkownika. Twoja aplikacja musi uwierzytelniać się jako aplikacja należąca do Twojego projektu w Konsoli interfejsów API Google. Jest to potrzebne do pomiaru wykorzystania projektu do celów księgowych.

Klucz interfejsu API: aby uwierzytelnić aplikację, użyj klucza interfejsu API na potrzeby projektu w Konsoli interfejsów API. Każde proste wywołanie dostępu, które wykonuje Twoja aplikacja, musi zawierać ten klucz.

2. Autoryzowany dostęp do interfejsu API (protokół OAuth 2.0)

Te wywołania interfejsu API uzyskują dostęp do prywatnych danych użytkownika. Zanim będzie można je wywołać, użytkownik, który ma dostęp do danych prywatnych, musi przyznać Twojej aplikacji dostęp. Dlatego Twoja aplikacja musi być uwierzytelniona, użytkownik musi przyznać dostęp do niej, a użytkownik musi być uwierzytelniony, aby ten dostęp mógł przyznać. Wszystko to można osiągnąć za pomocą protokołu protokołu OAuth 2.0 i napisanych do niego bibliotek.

Zakres: każdy interfejs API definiuje co najmniej 1 zakres, który deklaruje zestaw dozwolonych operacji. Na przykład interfejs API może mieć zakresy tylko do odczytu oraz do odczytu i zapisu. Gdy Twoja aplikacja prosi o dostęp do danych użytkownika, musi ono zawierać co najmniej 1 zakres. Użytkownik musi zatwierdzić zakres dostępu, o który prosi Twoja aplikacja.

Tokeny odświeżania i dostępu: gdy użytkownik przyzna dostęp Twojej aplikacji, serwer autoryzacji OAuth 2.0 udostępni aplikacji tokeny odświeżania i dostępu. Tokeny te są ważne tylko dla żądanego zakresu. Aplikacja używa tokenów dostępu do autoryzacji wywołań interfejsu API. Tokeny dostępu tracą ważność, ale tokeny odświeżania już nie. Aplikacja może użyć tokena odświeżania, aby uzyskać nowy token dostępu.

Client-ID i client tajny: te ciągi znaków jednoznacznie identyfikują aplikację i służą do uzyskania tokenów. Są one tworzone dla Twojego projektu w Konsoli interfejsów API. Istnieją 3 typy identyfikatorów klienta, więc sprawdź, czy pobierasz odpowiedni typ dla swojej aplikacji:

Przykłady

W tej sekcji znajdziesz przykłady prostego użycia interfejsu API bez autoryzacji. Więcej informacji o wywołaniach autoryzacji znajdziesz na stronie OAuth 2.0 dla .NET.

Przykład prostego interfejsu API

W tym przykładzie użyto prostego dostępu do interfejsu API aplikacji wiersza poleceń. Wywołuje on interfejs Google Discovery API, aby wyświetlić listę wszystkich interfejsów API Google.

Przykład konfiguracji

Uzyskiwanie klucza Simple API. Aby znaleźć klucz interfejsu API swojej aplikacji:

  1. Otwórz stronę Dane logowania w Konsoli interfejsów API.
  2. Ten interfejs API obsługuje 2 rodzaje danych logowania. Utwórz dane logowania odpowiednie dla Twojego projektu:

    • Protokół OAuth 2.0: za każdym razem, gdy Twoja aplikacja żąda prywatnych danych użytkownika, wraz z żądaniem musi wysłać token OAuth 2.0. Aplikacja najpierw wysyła identyfikator klienta, a być może tajny klucz klienta, aby uzyskać token. Dane logowania OAuth 2.0 możesz generować dla aplikacji internetowych, kont usługi lub zainstalowanych aplikacji.

      Więcej informacji znajdziesz w dokumentacji OAuth 2.0.

    • Klucze interfejsu API: żądanie, które nie zawiera tokena OAuth 2.0, musi wysłać klucz interfejsu API. Klucz identyfikuje projekt oraz zapewnia dostęp do interfejsu API, limity i raporty.

      Interfejs API obsługuje kilka typów ograniczeń dotyczących kluczy interfejsu API. Jeśli klucz interfejsu API, którego potrzebujesz, jeszcze nie istnieje, utwórz klucz interfejsu API w konsoli, klikając Utwórz dane logowania > Klucz interfejsu API. Możesz ograniczyć użycie klucza, zanim użyjesz go w środowisku produkcyjnym, klikając Ogranicz klucz i wybierając jedno z ograniczeń.

Aby zabezpieczyć klucze interfejsu API, postępuj zgodnie ze sprawdzonymi metodami bezpiecznego używania kluczy interfejsu API.

Przykładowy kod

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

Wskazówki dotyczące używania kluczy interfejsu API:

  • Jeśli chcesz korzystać z konkretnej usługi, musisz dodać do niej odwołanie. Jeśli na przykład chcesz korzystać z interfejsu Tasks API, zainstaluj jego pakiet NuGet Google.Apis.Tasks.v1.
  • Aby utworzyć instancję usługi, po prostu wywołaj jej konstruktor. Na przykład: new TasksService(new BaseClientService.Initializer {...});".
  • Wszystkie metody usługi znajdują się w poszczególnych zasobach w samym obiekcie usługi. Usługa wykrywania ma zasób Apis, który zawiera metodę List. Wywołanie metody service.Apis.List(..) powoduje zwracanie obiektu żądania kierowanego na tę metodę.
    Aby wykonać żądanie, wywołaj w nim metodę Execute() lub ExecuteAsyc().
  • Ustaw klucz interfejsu API za pomocą właściwości ApiKey w instancji BaseClientService.Initializer.

Znajdowanie informacji o interfejsach API

Strona Obsługiwane interfejsy API zawiera listę wszystkich interfejsów API, do których można uzyskać dostęp za pomocą tej biblioteki, a także linki do dokumentacji.

Możesz też korzystać z eksploratora interfejsów API, aby przeglądać interfejsy API, wyświetlać listę dostępnych metod, a nawet wypróbować wywołania API w przeglądarce.