Rozpocznij

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

Konfiguracja

Aby 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 Strona Zarządzanie projektami i utwórz projekt Konsola interfejsów API Google.
  3. Zainstaluj pakiet NuGet, z którym chcesz pracować.

Uwierzytelnianie i autoryzacja

Warto znać podstawy dotyczące uwierzytelniania i autoryzacji interfejsów API. Wszystkie wywołania interfejsu API muszą korzystać z dostępu prostego lub autoryzowanego (definiowanego poniżej). Wiele metod interfejsu API wymaga autoryzowanego dostępu, ale niektóre mogą korzystać z jednego z nich. niektóre metody API, które mogą działać inaczej, w zależności od tego, czy używasz dostępu prostego czy autoryzowanego. Aby określić odpowiedni typ dostępu, zapoznaj się z dokumentacją metody interfejsu API.

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

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

Klucz interfejsu API: Aby uwierzytelnić swoją aplikację, użyj Klucz interfejsu API dla projektu w konsoli API. Każde proste wywołanie dostępu wykonywane przez aplikację musi zawierać ten klucz.

2. Autoryzowany dostęp API (OAuth 2.0)

Te wywołania interfejsu API mają dostęp do prywatnych danych użytkowników. Zanim zadzwonisz, użytkownik mający dostęp do tych danych musi przyznać aplikacji dostęp. Aplikacja musi być więc uwierzytelniona, użytkownik musi przyznać dostęp do aplikacji, a użytkownik musi być uwierzytelniony, aby przyznać ten dostęp. Wszystko to jest możliwe dzięki Protokół OAuth 2.0 i napisane dla niego biblioteki.

Zakres: Każdy interfejs API definiuje jeden lub więcej zakresów, które deklarują zestaw dozwolonych operacji. Na przykład interfejs API może mieć zakresy tylko do odczytu oraz do odczytu i zapisu. Gdy aplikacja poprosi o dostęp do danych użytkownika, żądanie musi zawierać co najmniej 1 zakres. Użytkownik musi zatwierdzić zakres dostępu, o który prosi Twoja aplikacja.

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

Identyfikator klienta i tajny klucz klienta: Ciągi te jednoznacznie identyfikują aplikację i służą do pozyskiwania tokenów. Tworzone są na potrzeby Twojego projektu w konsoli interfejsów API. Są 3 rodzaje identyfikatorów klienta: pamiętaj więc, aby pobrać właściwy typ dla swojej aplikacji:

.

Przykłady

Ta sekcja przedstawia przykłady prostego użycia interfejsu API bez autoryzacji. Więcej informacji o wywołaniach autoryzacji znajdziesz tutaj: Strona OAuth 2.0 dla .NET

Przykład interfejsu Simple API

W tym przykładzie używamy prostego dostępu przez interfejs API w przypadku aplikacji wiersza poleceń. Nazywa się Google Discovery API do wyświetlania wszystkich interfejsów API Google.

Przykład konfiguracji

Uzyskaj klucz Simple API. Aby znaleźć klucz interfejsu API aplikacji, wykonaj te czynności:

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

    • OAuth 2.0: za każdym razem, gdy aplikacja żąda prywatnego konta użytkownika. musi wysyłać wraz z żądaniem token OAuth 2.0. Twoje aplikacja najpierw wysyła identyfikator klienta, a być może tajny klucz klienta mogą uzyskać token. Możesz generować dane logowania OAuth 2.0 na potrzeby stron internetowych aplikacje, konta usługi czy zainstalowane aplikacje.

      Więcej informacji znajdziesz w dokumentacji protokołu OAuth 2.0.

    • Klucze interfejsu API: Żądanie, które nie dostarcza tokena OAuth 2.0, musi wysłać interfejs API . Klucz identyfikuje projekt i zapewnia dostęp do interfejsu API, limit raportów.

      Interfejs API obsługuje kilka typów ograniczeń kluczy interfejsu API. Jeśli używany przez Ciebie klucz interfejsu API jeszcze nie istnieje, utwórz klucz interfejsu API w konsoli, kliknij Utwórz dane logowania.  > API. Możesz ograniczyć dostęp do klucza, zanim go użyjesz. w wersji produkcyjnej, klikając Ogranicz klucz i wybierając jedną z Ograniczenia.

Aby zabezpieczyć klucze interfejsu API, postępuj zgodnie ze sprawdzonymi metodami dotyczącymi bezpiecznie przy użyciu kluczy 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 korzystania z kluczy interfejsu API:

  • Aby używać określonej usługi, musisz dodać do niej odwołanie. Na przykład jeśli chcesz użyć tagu Tasks API, należy zainstalować jej 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 dotyczące 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. Gdy wywołujesz funkcję service.Apis.List(..), zwracany jest obiekt żądania kierowany 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

Obsługiwane interfejsy API lista 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ż użyć usługi Eksplorator interfejsów API do przeglądania interfejsów API, wyświetlania listy dostępnych metod, a nawet korzystania z wywołań interfejsu API w przeglądarce.