Начать

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

Настраивать

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

  1. Если у вас еще нет учетной записи Google, зарегистрируйтесь .
  2. Если вы никогда не создавали проект консоли Google API, прочтите страницу «Управление проектами» и создайте проект в консоли Google API .
  3. Установите пакет NuGet, с которым вы хотите работать.

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

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

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

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

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

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

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

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

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

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

Примеры

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

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

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

Настройка, например

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

  1. Откройте страницу «Учетные данные» в консоли API.
  2. Этот API поддерживает два типа учетных данных. Создайте учетные данные, подходящие для вашего проекта:
    • OAuth 2.0: всякий раз, когда ваше приложение запрашивает личные данные пользователя, оно должно отправить токен OAuth 2.0 вместе с запросом. Ваше приложение сначала отправляет идентификатор клиента и, возможно, секрет клиента для получения токена. Вы можете создать учетные данные OAuth 2.0 для веб-приложений, учетных записей служб или установленных приложений.

      Дополнительную информацию см. в документации OAuth 2.0 .

    • Ключи API. Запрос, который не предоставляет токен OAuth 2.0, должен отправить ключ API. Ключ идентифицирует ваш проект и обеспечивает доступ к API, квоту и отчеты.

      API поддерживает несколько типов ограничений для ключей API. Если нужный вам ключ API еще не существует, создайте ключ API в консоли, нажав Создать учетные данные > Ключ API . Вы можете ограничить ключ перед его использованием в рабочей среде, нажав «Ограничить ключ» и выбрав одно из «Ограничений» .

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

Код, например

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-обозреватель для просмотра API, получения списка доступных методов и даже попыток вызовов API из браузера.