Ta strona została przetłumaczona przez Cloud Translation API.

Wypróbuj

Dokument zawiera wszystkie podstawowe informacje potrzebne do korzystania z biblioteki. Omawiamy w nim zagadnienia związane z biblioteką, przykłady różnych przypadków użycia oraz linki do dodatkowych informacji.

Konfiguracja

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

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

Uwierzytelnianie i autoryzacja

Poznanie podstawowych zasad uwierzytelniania i uwierzytelniania interfejsu API jest bardzo ważne. Wszystkie wywołania interfejsu API muszą korzystać z prostego lub autoryzowanego dostępu (definicja poniżej). Wiele metod interfejsu API wymaga autoryzowanego dostępu, ale niektóre z nich mogą korzystać z tych rozwiązań. Niektóre metody interfejsu API, które mogą używać obu tych metod, działają w zależności od tego, czy używasz prostego, czy autoryzowanego dostępu. Aby określić odpowiedni typ dostępu, zapoznaj się z dokumentacją metody interfejsu API.

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

Te wywołania interfejsu API nie mają dostępu do żadnych prywatnych danych użytkownika. Aplikacja musi uwierzytelniać się jako aplikacja należąca do projektu w konsoli Google API. Jest to wymagane do pomiaru wykorzystania projektu na potrzeby księgowości.

Klucz interfejsu API: aby uwierzytelnić aplikację, użyj klucza interfejsu API dla projektu konsoli API. Ten klucz musi być wywoływany przez wszystkie proste wywołania dostępu, które aplikacja wysyła.

2. Autoryzowany dostęp API (OAuth 2.0)

Te wywołania interfejsu API uzyskują dostęp do prywatnych danych użytkowników. Zanim będzie można dzwonić do użytkowników, użytkownik mający dostęp do danych prywatnych musi przyznać aplikacji dostęp. W związku z tym Twoja aplikacja musi być uwierzytelniona, użytkownik musi przyznać dostęp do niej, a użytkownik musi uwierzytelnić się, aby udzielić dostępu. Wszystko to osiąga się za pomocą protokołu OAuth 2.0 i pisanych dla niego bibliotek.

Zakres: każdy interfejs API definiuje co najmniej 1 zakres, który deklaruje dozwolony zestaw operacji. Na przykład interfejs API może mieć zakresy tylko do odczytu i do odczytu i zapisu. Gdy aplikacja żąda dostępu do danych użytkownika, musi zawierać co najmniej jeden 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 do aplikacji, serwer autoryzacji OAuth 2.0 zapewni Twojej aplikacji tokeny odświeżania i dostępu. Te tokeny są ważne tylko w przypadku żądanego zakresu. Twoja aplikacja używa tokenów dostępu do autoryzowania wywołań interfejsu API. Tokeny dostępu wygasają, ale tokeny odświeżania nie wygasają. Aplikacja może użyć tokena odświeżania, aby uzyskać nowy token dostępu.

Client-ID i tajny klucz klienta: te ciągi znaków jednoznacznie identyfikują aplikację i służą do pozyskiwania tokenów. Są one tworzone dla projektu w konsoli API. Istnieją 3 typy identyfikatorów klienta, więc wybierz odpowiedni typ aplikacji:

Identyfikatory klientów aplikacji internetowych
Identyfikatory klientów zainstalowanych aplikacji
Identyfikatory klientów konta usługi

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.

Prosty przykład interfejsu API

Używany jest prosty dostęp do interfejsu wiersza poleceń aplikacji. Wywołuje interfejs Google Discovery API, aby wymienić wszystkie interfejsy API Google.

Przykład

Wygeneruj swój prosty klucz API. Aby znaleźć klucz interfejsu API aplikacji, wykonaj te czynności:

Otwórz stronę Dane logowania w konsoli interfejsu API.
Ten interfejs API obsługuje 2 typy danych logowania. Utwórz odpowiednie dane logowania do swojego projektu:
- OAuth 2.0: gdy aplikacja żąda prywatnych danych użytkownika, musi wraz z żądaniem wysłać token OAuth 2.0. Aplikacja najpierw wysyła identyfikator klienta, a być może także klucz klienta, aby uzyskać token. Możesz wygenerować dane logowania OAuth 2.0 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 udostępnia tokena OAuth 2.0, musi wysłać klucz interfejsu API. Klucz identyfikuje projekt i udostępnia dostęp do interfejsu API, limit oraz raporty.
  
  Interfejs API obsługuje kilka typów ograniczeń dotyczących kluczy interfejsu API. Jeśli klucz interfejsu API, którego potrzebujesz, nie istnieje, utwórz klucz interfejsu API w konsoli, klikając Utwórz dane logowania i klucz interfejsu API. Możesz ograniczyć klucz przed użyciem go w środowisku produkcyjnym, klikając Ogranicz klucz i wybierając jedno z ograniczeń.

Aby zapewnić bezpieczeństwo kluczy API, postępuj zgodnie ze sprawdzonymi metodami korzystania z kluczy interfejsu API.

Na przykład 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 korzystania z kluczy interfejsu API:

Aby użyć konkretnej usługi, musisz dodać do niej odwołanie. Jeśli na przykład chcesz używać interfejsu Tasks API, zainstaluj 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 obiekcie usługi. Usługa wykrywania zawiera zasób Apis, który zawiera metodę List. Gdy wywołasz service.Apis.List(..), zostanie zwrócony obiekt żądania kierowany na tę metodę.
Aby wykonać żądanie, wywołaj do niego metodę Execute() lub ExecuteAsyc().
Ustaw klucz interfejsu API za pomocą właściwości ApiKey w instancji BaseClientService.Initializer.

Znajdowanie informacji na temat interfejsów API

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

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