Primeiros passos

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

Configuração

É preciso concluir algumas etapas de configuração para usar a biblioteca:

  1. Se você ainda não tem uma Conta do Google, Inscreva-se.
  2. Se você nunca criou um projeto no Console de APIs do Google, leia Página "Como gerenciar projetos" e criar um projeto 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 um 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 qualquer um dos dois 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 particulares do usuário. O aplicativo precisa ser autenticado como um aplicativo pertencente ao projeto do Console de APIs do Google. Isso é necessário para medir o uso do projeto para fins contábeis.

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

2. Acesso autorizado à API (OAuth 2.0)

Essas chamadas de API acessam dados particulares do usuário. Antes de ligar para eles, o usuário que tem acesso aos dados privados precisa conceder acesso ao seu aplicativo. Portanto, seu aplicativo precisa ser autenticado, o usuário precisa conceder acesso ao seu aplicativo, e o usuário precisa ser autenticado para conceder esse acesso. Tudo isso é realizado com 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 a seu aplicativo, o servidor de autorização OAuth 2.0 fornece tokens de atualização e acesso ao aplicativo. Esses tokens são válidos somente 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 e chave secreta do cliente: Essas strings identificam seu aplicativo de forma exclusiva e são usadas para adquirir tokens. Elas são criadas para seu projeto no Console de APIs. Há três tipos de IDs do cliente: Portanto, certifique-se de obter o tipo correto para seu aplicativo:

.

Exemplos

Nesta seção, você verá 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 acesso simples à API para um aplicativo de linha de comando. Ele chama o método API Google Discovery para listar todas as APIs do Google.

Configuração, por exemplo

Gere sua chave de API simples. Para encontrar a chave de API do 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 que você necessário ainda não existe, crie uma chave de API no console clicando em Criar credenciais  > Chave de API. É possível restringir a chave antes de usá-la em produção clicando em Restringir chave e selecionando um dos Restrições.

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

Código para 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, você precisa adicionar uma referência a ele. Por exemplo, se você quiser usar 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 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.

Encontrar informações sobre as APIs

A APIs compatíveis lista todas as APIs que podem ser acessadas usando essa biblioteca, além de links para a documentação.

Você também pode usar o APIs Explorer para navegar pelas APIs, listar métodos disponíveis e até mesmo tentar chamadas de API em seu navegador.