시작하기

이 문서에서는 라이브러리 사용을 시작하는 데 필요한 모든 기본 정보를 제공합니다. 여기서는 라이브러리 개념을 다루고 다양한 사용 사례의 예를 보여주며 추가 정보 링크를 제공합니다.

설정

이 라이브러리를 사용하려면 다음 몇 가지 설정 단계를 완료해야 합니다.

  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에 읽기 전용 및 읽기-쓰기 범위가 있을 수 있습니다. 애플리케이션에서 사용자 데이터에 대한 액세스를 요청할 때 요청에 범위를 1개 이상 포함해야 합니다. 사용자는 애플리케이션이 요청하는 액세스 범위를 승인해야 합니다.

갱신 및 액세스 토큰: 사용자가 애플리케이션에 액세스 권한을 부여하면 OAuth 2.0 승인 서버가 갱신 및 액세스 토큰을 애플리케이션에 제공합니다. 이 토큰은 요청된 범위에만 유효합니다. 애플리케이션은 액세스 토큰을 사용하여 API 호출을 승인합니다. 액세스 토큰은 만료되지만 갱신 토큰은 만료되지 않습니다. 애플리케이션은 갱신 토큰을 사용하여 새 액세스 토큰을 얻을 수 있습니다.

클라이언트 ID 및 클라이언트 비밀번호: 이 문자열은 애플리케이션을 고유하게 식별하고 토큰을 얻는 데 사용됩니다. API 콘솔에서 프로젝트에 대해 생성됩니다. 클라이언트 ID에는 세 가지 유형이 있으므로 애플리케이션에 적합한 유형을 가져와야 합니다.

이 섹션에는 승인 없이 간단한 API를 사용하는 예가 나와 있습니다. 승인 호출에 대한 자세한 내용은 .NET용 OAuth 2 .0 페이지를 참조하세요.

간단한 API 예

이 예에서는 명령줄 애플리케이션에 간단한 API 액세스를 사용합니다. Google Discovery API를 호출하여 모든 Google API를 나열합니다.

설정 예시

Simple API 키 가져오기 애플리케이션의 API 키를 찾으려면 다음 단계를 따르세요.

  1. API 콘솔에서 사용자 인증 정보 페이지를 엽니다.
  2. 이 API는 두 가지 유형의 사용자 인증 정보를 지원합니다. 프로젝트에 적합한 사용자 인증 정보를 만듭니다.
    • OAuth 2.0: 애플리케이션에서 비공개 사용자 데이터를 요청할 때마다 요청과 함께 OAuth 2.0 토큰을 보내야 합니다. 애플리케이션은 먼저 토큰을 획득하기 위해 클라이언트 ID나 클라이언트 보안 비밀번호를 보냅니다. 웹 애플리케이션, 서비스 계정, 설치된 애플리케이션의 OAuth 2.0 사용자 인증 정보를 생성할 수 있습니다.

      자세한 내용은 OAuth 2.0 문서를 참조하세요.

    • API 키: OAuth 2.0 토큰을 제공하지 않는 요청은 API 키를 전송해야 합니다. 키는 프로젝트를 식별하고 API 액세스, 할당량, 보고서를 제공합니다.

      API는 여러 유형의 API 키 제한 사항을 지원합니다. 필요한 API 키가 아직 없는 경우 사용자 인증 정보 만들기 > API 키를 클릭하여 Console에서 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 {...});"입니다.
  • 서비스의 모든 메서드는 서비스 객체 자체의 개별 리소스에 있습니다. 검색 서비스에는 List 메서드가 포함된 Apis 리소스가 있습니다. service.Apis.List(..)를 호출하면 이 메서드를 타겟팅하는 요청 객체가 반환됩니다.
    요청을 실행하려면 요청에 대해 Execute() 또는 ExecuteAsyc() 메서드를 호출합니다.
  • BaseClientService.Initializer 인스턴스에서 ApiKey 속성을 사용하여 API 키를 설정합니다.

API에 대한 정보 찾기

지원되는 API 페이지에는 이 라이브러리를 사용하여 액세스할 수 있는 모든 API와 문서 링크가 나와 있습니다.

또한 API 탐색기를 사용하여 API를 탐색하고 사용 가능한 메서드를 나열하며 브라우저에서 API 호출을 시도해 볼 수도 있습니다.