Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Начало работы

В этом документе содержится вся основная информация, необходимая для начала работы с библиотекой. В ней рассматриваются основные понятия, приводятся примеры для различных сценариев использования и даются ссылки на дополнительную информацию.

Настройка

Прежде чем использовать эту библиотеку, необходимо выполнить несколько шагов по настройке:

Если у вас нет аккаунта Google, зарегистрируйтесь.
Если вы никогда не создавали проект в Google API Console, прочитайте эту статью и создайте проект в Google API Console.
Установите нужный пакет NuGet.

Аутентификация и авторизация

Важно понимать, как выполняются аутентификация и авторизация API. Для всех вызовов API должен использоваться простой или авторизованный доступ (определения приведены ниже). Для многих методов API требуется авторизованный доступ, но некоторые могут использовать оба варианта. Некоторые методы API, которые могут использовать оба типа доступа, ведут себя по-разному в зависимости от того, какой тип доступа вы используете. Чтобы определить подходящий тип доступа, ознакомьтесь с документацией по методам API.

1. Простой доступ к API (ключи API)

Эти вызовы API не получают доступа к личным пользовательским данным. Приложение должно пройти аутентификацию как принадлежащее вашему проекту Google API Console. Это необходимо для учета использования проекта в бухгалтерских целях.

Ключ API. Чтобы выполнить аутентификацию приложения, используйте ключ API для проекта API Console. Этот ключ должен быть включен в каждый простой вызов доступа, выполняемый вашим приложением.

2. Авторизованный доступ к API (OAuth 2.0)

Эти вызовы API получают доступ к личным данным пользователей. Прежде чем вы сможете их вызвать, пользователь, у которого есть доступ к конфиденциальным данным, должен предоставить вашему приложению доступ. Поэтому ваше приложение должно пройти аутентификацию, пользователь должен предоставить ему доступ, а для этого он сам должен пройти аутентификацию. Все это достигается с помощью OAuth 2.0 и библиотек, написанных для него.

Область действия. Каждый API определяет одну или несколько областей действия, которые объявляют набор разрешенных операций. Например, у API могут быть области действия "только чтение" и "чтение и запись". Когда приложение запрашивает доступ к пользовательским данным, в запросе должна быть указана одна или несколько областей действия. Пользователь должен одобрить область доступа, которую запрашивает ваше приложение.

Токены обновления и доступа. Когда пользователь предоставляет приложению доступ, сервер авторизации OAuth 2.0 предоставляет приложению токены обновления и доступа. Эти токены действительны только для запрошенной области действия. Для авторизации вызовов API в приложении используются токены доступа. Срок действия токенов доступа ограничен, а токенов обновления – нет. Приложение может использовать токен обновления, чтобы получить новый токен доступа.

Идентификатор клиента и секретный код клиента. Эти строки уникальным образом идентифицируют ваше приложение и используются для получения токенов. Они создаются для вашего проекта в API Console. Существует три типа идентификаторов клиента. Выберите тот, который подходит для вашего приложения:

Идентификаторы клиентов веб-приложений
Идентификаторы клиентов установленных приложений
Сервисный аккаунт: идентификаторы клиентов

Примеры

В этом разделе приведены примеры простого использования API без авторизации. Дополнительную информацию о вызовах авторизации можно найти на странице OAuth 2.0 для .NET.

Простой пример API

В этом примере используется простой доступ к API для приложения командной строки. Он вызывает Google Discovery API, чтобы получить список всех API Google.

Пример настройки

Получите ключ Simple API. Чтобы найти ключ API приложения, выполните следующие действия:

Откройте раздел Учетные данные в API Console.
В этом API поддерживаются Создайте учетные данные, подходящие для вашего проекта:
- OAuth 2.0. При запросе закрытых пользовательских данных приложение должно отправлять токен OAuth 2.0. Сначала приложение отправляет идентификатор клиента и, возможно, секретный код клиента, чтобы получить токен. Учетные данные OAuth 2.0 можно создавать для веб-приложений, сервисных аккаунтов и установленных приложений.
  
  Подробнее…
- Ключи API. Запрос без токена OAuth 2.0 должен содержать ключ API, который идентифицирует ваш проект и определяет доступные вам разрешения, квоты и отчеты.
  
  API поддерживает несколько типов ограничений для ключей API. Если нужного ключа API нет, создайте его в консоли, нажав Create credentials (Создать учетные данные) > API key (Ключ API). Вы можете ограничить ключ, прежде чем использовать его в рабочей среде. Для этого нажмите Restrict key (Ограничить ключ) и выберите один из вариантов в разделе Restrictions (Ограничения).

Пример кода

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

Советы по использованию ключей API:

Чтобы использовать определенный сервис, необходимо добавить ссылку на него. Например, если вы хотите использовать Tasks API, установите пакет NuGet Google.Apis.Tasks.v1.
Чтобы создать экземпляр сервиса, просто вызовите его конструктор. Пример: new TasksService(new BaseClientService.Initializer {...});".
Все методы сервиса находятся в отдельных ресурсах в самом объекте сервиса. Сервис Discovery содержит ресурс Apis, в котором есть метод List. При вызове service.Apis.List(..) возвращается объект запроса, предназначенный для этого метода.
Чтобы выполнить запрос, вызовите для него метод Execute() или ExecuteAsyc().
Задайте ключ API с помощью свойства ApiKey в экземпляре BaseClientService.Initializer.

Как найти информацию об API

На странице Поддерживаемые API перечислены все API, к которым можно получить доступ с помощью этой библиотеки, а также приведены ссылки на документацию.

Вы также можете использовать API Explorer, чтобы просматривать API, перечислять доступные методы и даже пробовать вызовы API из браузера.