이 문서에서는 라이브러리 사용을 시작하는 데 필요한 모든 기본 정보를 제공합니다. 라이브러리 개념을 다루고 다양한 사용 사례의 예를 보여주며 더 많은 정보에 대한 링크를 제공합니다.
설정
이 라이브러리를 사용하려면 몇 가지 설정 단계를 완료해야 합니다.
- 아직 Google 계정이 없다면 가입하세요.
- Google API 콘솔 프로젝트를 처음 만드는 경우 프로젝트 관리 페이지를 읽고 Google API 콘솔에서 프로젝트를 만드세요.
- 작업할 NuGet 패키지를 설치합니다.
인증 및 승인
API 인증 및 승인 처리 방법의 기본사항을 이해하는 것이 중요합니다. 모든 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 호출을 승인합니다. 액세스 토큰은 만료되지만 갱신 토큰은 만료되지 않습니다. 애플리케이션은 갱신 토큰을 사용하여 새 액세스 토큰을 얻을 수 있습니다.
클라이언트 ID 및 클라이언트 보안 비밀번호: 이러한 문자열은 애플리케이션을 고유하게 식별하고 토큰을 얻는 데 사용됩니다. API 콘솔에서 프로젝트에 생성됩니다. 클라이언트 ID에는 세 가지 유형이 있으므로 애플리케이션에 적합한 유형을 가져와야 합니다.
- 웹 애플리케이션 클라이언트 ID
- 설치된 애플리케이션 클라이언트 ID
- 서비스 계정 클라이언트 ID
예
이 섹션에서는 승인이 없는 간단한 API 사용의 예를 보여줍니다. 승인 호출에 관한 자세한 내용은 .NET용 OAuth 2 .0 페이지를 참고하세요.
간단한 API 예
이 예에서는 명령줄 애플리케이션에 간단한 API 액세스를 사용합니다. Google Discovery API를 호출하여 모든 Google API를 나열합니다.
설정 예시
Simple API 키 받기 애플리케이션의 API 키를 찾으려면 다음 단계를 따르세요.
- API 콘솔에서 사용자 인증 정보 페이지를 엽니다.
-
이 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 호출을 시도할 수도 있습니다.