Comece agora

Este documento fornece 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

Você precisa seguir algumas etapas de configuração 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 o acesso simples ou autorizado (definido abaixo). Muitos métodos de API exigem acesso autorizado, mas alguns podem usar qualquer um deles. Alguns métodos de API que podem usar ambos se comportam de maneira diferente, dependendo do 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 privados do usuário. Seu aplicativo precisa se autenticar como um aplicativo pertencente ao seu 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 o aplicativo, use uma chave de API no projeto do Console de APIs. Todas as chamadas de acesso simples que seu aplicativo faz precisam incluir essa chave.

2. Acesso autorizado à API (OAuth 2.0)

Essas chamadas de API acessam dados privados do usuário. Antes de chamá-los, o usuário que tem acesso aos dados particulares precisa conceder acesso ao seu aplicativo. Portanto, seu aplicativo precisa ser autenticado, o usuário precisa conceder acesso ao seu aplicativo e autenticado para conceder esse acesso. Tudo isso é feito com o OAuth 2.0 e bibliotecas criadas 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 leitura/gravação. Quando seu aplicativo solicita acesso aos 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 OAuth 2.0 fornece tokens de atualização e acesso ao aplicativo. 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 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 seu aplicativo de maneira exclusiva e são usadas para adquirir tokens. Elas são criadas para o projeto no Console de APIs. Há três tipos de IDs do cliente. Portanto, escolha o tipo correto para seu aplicativo:

Exemplos

Nesta seção, há exemplos de uso simples da 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 o acesso simples à API para um aplicativo de linha de comando. Ela chama a API Google Discovery para listar todas as APIs do Google.

Configuração de exemplo

Gere a 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 apropriadas 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 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 as chaves de API:

  • Para usar um serviço específico, é preciso 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 seu construtor. 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 de descoberta tem um recurso Apis, que contém um método List. Quando você chama service.Apis.List(..), um objeto de solicitação direcionado a esse método é retornado.
    Para executar uma solicitação, chame o método Execute() ou ExecuteAsyc() nela.
  • 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, além de links para a documentação.

Também é possível usar o APIs Explorer para procurar APIs, listar métodos disponíveis e até testar chamadas de API do navegador.