Başla

Bu dokümanda, kitaplığı kullanmaya başlamak için ihtiyacınız olan tüm temel bilgiler yer almaktadır. Kitaplık kavramlarını ele alır, çeşitli kullanım alanlarına dair örnekler gösterir ve daha fazla bilgiye yönlendiren bağlantılar sunar.

Kurulum

Bu kitaplığı kullanabilmek için tamamlamanız gereken birkaç kurulum adımı vardır:

  1. Google Hesabınız yoksa kaydolun.
  2. Daha önce Google API Konsolu projesi oluşturmadıysanız Projeleri Yönetme sayfasını okuyun ve Google API Konsolu'nda proje oluşturun.
  3. Çalışmak istediğiniz NuGet paketini yükleyin.

Kimlik doğrulama ve yetkilendirme

API kimlik doğrulama ve yetkilendirmesinin nasıl ele alındığına dair temel bilgileri anlamak önemlidir. Tüm API çağrılarında basit veya yetkili erişim (aşağıda tanımlanmıştır) kullanılmalıdır. Birçok API yöntemi, yetkilendirilmiş erişim gerektirir ancak bazıları her ikisini de kullanabilir. Kullanabilen bazı API yöntemleri, basit veya yetkili erişim kullanmanıza bağlı olarak farklı davranışlar sergiler. Uygun erişim türünü belirlemek için API'nin yöntem dokümanlarına bakın.

1. Basit API erişimi (API anahtarları)

Bu API çağrıları hiçbir gizli kullanıcı verisine erişmez. Uygulamanız, Google API Konsolu projenize ait bir uygulama olarak kimliğini doğrulamalıdır. Muhasebe amacıyla proje kullanımını ölçmek için gereklidir.

API anahtarı: Uygulamanızın kimliğini doğrulamak için API Konsolu projenizde bir API anahtarı kullanın. Uygulamanızın yaptığı her basit erişim çağrısı bu anahtarı içermelidir.

2. Yetkilendirilmiş API erişimi (OAuth 2.0)

Bu API çağrıları gizli kullanıcı verilerine erişir. Bunları çağırabilmeniz için gizli verilere erişimi olan kullanıcının uygulamanıza erişim izni vermesi gerekir. Dolayısıyla, uygulamanızın kimliğinin doğrulanması, kullanıcının uygulamanıza erişim izni vermesi ve bu erişimi verebilmek için kullanıcının kimliğinin doğrulanması gerekir. Tüm bunlar OAuth 2.0 ve bunun için yazılan kitaplıklar ile gerçekleştirilir.

Kapsam: Her API, izin verilen bir işlem grubunu tanımlayan bir veya daha fazla kapsam tanımlar. Örneğin, bir API'nin salt okuma ve okuma-yazma kapsamları olabilir. Uygulamanız kullanıcı verilerine erişim istediğinde, isteğin bir veya daha fazla kapsam içermesi gerekir. Kullanıcının, uygulamanızın istediği erişim kapsamını onaylaması gerekir.

Yenileme ve erişim jetonları: Bir kullanıcı uygulamanıza erişim izni verdiğinde OAuth 2.0 yetkilendirme sunucusu, uygulamanıza yenileme ve erişim jetonları sağlar. Bu jetonlar, yalnızca istenen kapsam için geçerlidir. Uygulamanız, API çağrılarını yetkilendirmek için erişim jetonları kullanır. Erişim jetonlarının süresi dolar, ancak yenileme jetonlarının süresi dolmaz. Uygulamanız, yeni bir erişim jetonu almak için yenileme jetonu kullanabilir.

İstemci kimliği ve istemci gizli anahtarı: Bu dizeler, uygulamanızı benzersiz bir şekilde tanımlar ve jetonları edinmek için kullanılır. Bu API'ler API Konsolu'nda projeniz için oluşturulur. Üç tür istemci kimliği vardır. Bu nedenle, uygulamanız için doğru türü aldığınızdan emin olun:

Örnekler

Bu bölümde, yetkilendirme olmadan basit API kullanımına örnekler verilmiştir. Yetkilendirme çağrıları hakkında daha fazla bilgi için .NET için OAuth 2 .0 sayfasını inceleyin.

Basit API örneği

Bu örnekte, bir komut satırı uygulaması için basit API erişimi kullanılmaktadır. Tüm Google API'lerini listelemek için Google Discovery API'yi çağırır.

Örneğin, kurulum

Basit API anahtarınızı alın. Uygulamanızın API anahtarını bulmak için aşağıdakileri yapın:

  1. API Konsolu'nda Kimlik Bilgileri sayfasını açın.
  2. Bu API, iki tür kimlik bilgisini destekler. Projeniz için uygun kimlik bilgilerini oluşturun:
    • OAuth 2.0: Uygulamanız, gizli kullanıcı verileri istediğinde istekle birlikte bir OAuth 2.0 jetonu göndermelidir. Uygulamanız önce bir istemci kimliği ve muhtemelen jeton almak için bir istemci gizli anahtarı gönderir. Web uygulamaları, hizmet hesapları veya yüklü uygulamalar için OAuth 2.0 kimlik bilgileri oluşturabilirsiniz.

      Daha fazla bilgi için OAuth 2.0 dokümanlarına bakın.

    • API anahtarları: OAuth 2.0 jetonu sağlamayan istek, bir API anahtarı göndermelidir. Anahtar projenizi tanımlar ve API erişimi, kota ve rapor sağlar.

      API, API anahtarlarında çeşitli kısıtlama türlerini destekler. İhtiyacınız olan API anahtarı yoksa Kimlik bilgileri oluştur > API anahtarı'nı tıklayarak Konsol'da bir API anahtarı oluşturun. Anahtarı, üretimde kullanmadan önce Anahtarı kısıtla'yı tıklayıp Kısıtlamalar'dan birini seçerek kısıtlayabilirsiniz.

API anahtarlarınızı güvende tutmak için API anahtarlarını güvenli bir şekilde kullanma ile ilgili en iyi uygulamaları izleyin.

Örneğin kod

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 anahtarlarını kullanmayla ilgili ipuçları:

  • Belirli bir hizmeti kullanmak için ilgili hizmete referans eklemeniz gerekir. Örneğin Tasks API'yi kullanmak istiyorsanız NuGet paketini Google.Apis.Tasks.v1'i yüklemeniz gerekir.
  • Bir hizmetin örneğini oluşturmak için kurucuyu çağırmanız yeterlidir. Örneğin: new TasksService(new BaseClientService.Initializer {...});".
  • Bir hizmetin tüm yöntemleri, hizmet nesnesinin kendisindeki bağımsız kaynaklarda bulunur. Keşif hizmetinin, List yöntemi içeren bir Apis kaynağı var. service.Apis.List(..) çağırdığınızda, bu yöntemi hedefleyen bir istek nesnesi döndürülür.
    Bir isteği yürütmek için istekte Execute() veya ExecuteAsyc() yöntemini çağırın.
  • BaseClientService.Initializer örneğinde ApiKey özelliğini kullanarak API anahtarını ayarlayın.

API'ler hakkında bilgi bulma

Desteklenen API'ler sayfasında bu kitaplığı kullanarak erişilebilen tüm API'lerin yanı sıra belge bağlantıları listelenir.

API'lere göz atmak, kullanılabilir yöntemleri listelemek ve hatta tarayıcınızdan API çağrılarını denemek için API Gezgini'ni de kullanabilirsiniz.