Começar

Esse documento contém todas as informações básicas necessárias para começar a usar a biblioteca. Ele aborda os conceitos da biblioteca, mostra exemplos para vários casos de uso e fornece links para mais informações.

Configuração

Há algumas etapas de configuração que você precisa concluir antes de usar essa biblioteca:

  1. Se você ainda não tem uma Conta do Google, inscreva-se.
  2. Se você nunca criou um projeto do Console de APIs do Google, leia a página Como gerenciar projetos e crie um projeto no Console de APIs do Google.
  3. Instale o pacote NuGet com que você quer trabalhar.

Autenticação e autorização

É importante entender os conceitos básicos de como a autenticação e a autorização da API são tratadas. Todas as chamadas de API precisam usar acesso simples ou autorizado (definido abaixo). Muitos métodos de API exigem acesso autorizado, mas alguns podem usar qualquer um. Alguns métodos de API que podem se comportar de maneira diferente dependem do uso de acesso simples ou autorizado. Consulte a documentação do método da API para determinar o tipo de acesso apropriado.

1. Acesso simples à API (chaves de API)

Essas chamadas de API não acessam dados particulares do usuário. Seu aplicativo precisa se autenticar como um aplicativo pertencente ao projeto do Console de APIs do Google. Isso é necessário para medir o uso do projeto para fins de contabilidade.

Chave de API: para autenticar seu aplicativo, use uma chave de API no projeto do Console de APIs. Todas as chamadas de acesso simples feitas pelo seu aplicativo precisam incluir essa chave.

2. Acesso autorizado à API (OAuth 2.0)

Essas chamadas de API acessam dados particulares do usuário. Antes de chamá-los, o usuário que tem acesso aos dados particulares precisa conceder ao seu aplicativo acesso. Portanto, seu aplicativo precisa ser autenticado, o usuário precisa conceder acesso a ele e o usuário precisa estar autenticado para conceder esse acesso. Tudo isso é feito com o OAuth 2.0 e as bibliotecas escritas para ele.

Escopo: cada API define um ou mais escopos que declaram um conjunto de operações permitidas. Por exemplo, uma API pode ter escopos somente leitura e de leitura/gravação. Quando seu aplicativo solicita acesso a dados do usuário, a solicitação precisa incluir um ou mais escopos. O usuário precisa aprovar o escopo de acesso que seu aplicativo está solicitando.

Tokens de atualização e acesso: quando um usuário concede acesso ao aplicativo, o servidor de autorização do OAuth 2.0 fornece a ele os tokens de atualização e acesso. Esses tokens são válidos apenas para o escopo solicitado. Seu aplicativo usa tokens de acesso para autorizar chamadas de API. Os tokens de acesso expiram, mas os tokens de atualização não. Seu aplicativo pode usar um token de atualização para adquirir um novo token de acesso.

ID do cliente e chave secreta do cliente: essas strings identificam exclusivamente seu aplicativo e são usadas para adquirir tokens. Elas são criadas para seu projeto no Console de APIs. Há três tipos de IDs de cliente, portanto, verifique se você está no tipo certo para o aplicativo:

Exemplos

Nesta seção, há exemplos de uso simples de API sem autorização. Para mais informações sobre chamadas de autorização, consulte a página do OAuth 2.0 para .NET.

Exemplo de API simples

Este exemplo usa acesso simples à API para um aplicativo de linha de comando. Ela chama a API Google Discovery para listar todas as APIs do Google.

Configurar, por exemplo

Receba sua chave de API simples. Para encontrar a chave de API do seu aplicativo, faça o seguinte:

  1. Abra a página Credenciais no Console da API.
  2. Essa API aceita dois tipos de credenciais. Crie as credenciais adequadas para seu projeto:

    • OAuth 2.0: sempre que seu aplicativo solicitar dados particulares do usuário, ele deverá enviar um token OAuth 2.0 junto da solicitação. Primeiro, seu aplicativo envia um ID de cliente e, possivelmente, uma chave secreta do cliente para obter um token. É possível gerar credenciais OAuth 2.0 para aplicativos da Web, contas de serviço ou aplicativos instalados.

      Para mais informações, acesse a documentação do OAuth 2.0.

    • Chaves de API: uma solicitação que não fornece um token OAuth 2.0 precisa enviar uma chave de API. A chave identifica seu projeto e fornece acesso à API, à cota e aos relatórios.

      A API é compatível com diversos tipos de restrições em chaves de API. Se a chave de API de que você precisa ainda não existe, crie uma chave de API no Console clicando em Criar credenciais > Chave de API. Para restringir a chave antes de usá-la na produção, clique em Restringir chave e selecione uma das Restrições.

Para proteger as chaves de API, siga as práticas recomendadas para usar as chaves de API com segurança.

Código, por exemplo

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

Dicas para usar chaves de API:

  • Para usar um serviço específico, é necessário adicionar uma referência a ele. Por exemplo, se você quiser usar a API Tasks, instale o pacote NuGet Google.Apis.Tasks.v1.
  • Para criar uma instância de um serviço, basta chamar o construtor dele. Exemplo: new TasksService(new BaseClientService.Initializer {...});".
  • Todos os métodos de um serviço estão localizados em recursos individuais no próprio objeto de serviço. O serviço Discovery tem um recurso Apis, que contém um método List. Quando você chama service.Apis.List(..), um objeto de solicitação que segmenta esse método é retornado.
    Para executar uma solicitação, chame o método Execute() ou ExecuteAsyc() em uma solicitação.
  • Defina a chave de API usando a propriedade ApiKey na instância BaseClientService.Initializer.

Como encontrar informações sobre as APIs

A página APIs compatíveis lista todas as APIs que podem ser acessadas usando essa biblioteca, bem como links para a documentação.

Você também pode usar o APIs Explorer para procurar APIs, listar métodos disponíveis e até mesmo testar chamadas de API do navegador.