Akıllı ev işlemlerinin nasıl geliştirileceğini öğrenebileceğiniz yeni adres olan Google Home Geliştirici Merkezi'ne hoş geldiniz. Not: Actions Console'da işlem derlemeye devam edersiniz.

OAuth 2.0 sunucusu uygulama

Her smart home işlemi, kullanıcıların kimliğini doğrulamak için bir mekanizma içermelidir.

Kimlik doğrulama sayesinde kullanıcılarınızın Google hesaplarını, kimlik doğrulama sisteminizdeki kullanıcı hesaplarına bağlayabilirsiniz. Bu, sipariş karşılama ölçütünüz akıllı ev niyeti aldığında kullanıcılarınızı belirlemenize olanak tanır. Google akıllı ev, yalnızca yetkilendirme kodu akışı olan OAuth'u destekler.

Bu sayfada, OAuth 2.0 sunucunuzu smart home İşleminizle çalışacak şekilde nasıl ayarlayacağınız açıklanmaktadır.

Yetkilendirme kodu akışı

Yetkilendirme kodu akışının OAuth 2.0 sunucusu uygulaması, hizmetinizin HTTPS tarafından kullanıma sunulduğu iki uç noktadan oluşur. İlk uç nokta, veri erişimi için kullanıcılardan izin almak veya izin almaktan sorumlu yetkilendirme uç noktasıdır. Yetkilendirme uç noktası, kullanıcılarınıza halihazırda oturum açmamış bir oturum açma kullanıcı arayüzü sunar ve istenen erişim için izni kaydeder. İkinci uç nokta, kullanıcının hizmetinize erişme yetkisi veren şifrelenmiş dizeler olarak adlandırılan jeton değişimi uç noktasıdır.

Bir Google uygulamasının, hizmetinizin API'lerinden birini çağırması gerektiğinde, kullanıcılarınızdan bu API'leri onlar adına çağırmak için bu uç noktaları birlikte kullanır.

Google tarafından başlatılan bir OAuth 2.0 yetkilendirme kodu akış oturumunda aşağıdaki akış gerçekleşir:

  1. Google, yetkilendirme uç noktasını kullanıcının tarayıcısında açar. Akış bir Action için yalnızca sesli cihazda başlatılmışsa Google, yürütme işlemini bir telefona aktarır.
  2. Kullanıcı henüz oturum açmamışsa oturum açar ve henüz izin vermemişse Google'a API'nizle verilerine erişme izni verir.
  3. Hizmetiniz bir yetkilendirme kodu oluşturur ve Google'a geri gönderir. Bunu yapmak için kullanıcının tarayıcısını, isteğe eklenmiş yetkilendirme koduyla Google'a yönlendirin.
  4. Google, yetkilendirme kodunu jeton exchange uç noktanıza gönderir. Bu, kodun orijinalliğini doğrular ve bir erişim jetonu ile yenileme jetonu döndürür. Erişim jetonu, hizmetinizin API'lere erişmek için kimlik bilgileri olarak kabul ettiği kısa ömürlü bir jetondur. Yenileme jetonu, Google'ın depoladığı ve yeni erişim jetonları almak için kullanabileceği uzun ömürlü bir jetondur.
  5. Kullanıcı hesap bağlama akışını tamamladıktan sonra, Google'dan gönderilen her istekte bir erişim jetonu bulunur.

Yetkilendirme isteklerini işleme

OAuth 2.0 yetkilendirme kodu akışını kullanarak hesap bağlama işlemi gerçekleştirmeniz gerektiğinde Google, aşağıdaki parametreleri içeren bir isteği içeren kullanıcıyı yetkilendirme uç noktanıza gönderir:

Yetkilendirme uç noktası parametreleri
client_id Google'a atadığınız İstemci Kimliği.
redirect_uri Bu isteğe yanıt gönderdiğiniz URL.
state Yönlendirme URI'sında değişiklik olmadan Google'a geri aktarılan bir muhasebe değeri.
scope İsteğe bağlı: Google'ın yetkilendirme istediği verileri belirten, boşlukla sınırlandırılmış bir kapsam dizeleri grubu.
response_type Yanıtta döndürülecek değerin türü. OAuth 2.0 yetkilendirme kodu akışı için yanıt türü her zaman code'dir.
user_locale İçeriğinizi kullanıcının tercih ettiği dilde yerelleştirmek için RFC5646 biçimindeki Google Hesabı dil ayarı.

Örneğin, yetkilendirme uç noktanız https://myservice.example.com/auth adresinde kullanılabiliyorsa bir istek aşağıdaki gibi görünebilir:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

Yetkilendirme uç noktanızın oturum açma isteklerini işlemesi için aşağıdaki adımları uygulayın:

  1. client_id öğesinin, Google'a atadığınız İstemci Kimliği ile ve redirect_uri hizmetinin, hizmetiniz için Google tarafından sağlanan yönlendirme URL'siyle eşleştiğini doğrulayın. Bu kontroller, istenmeyen veya yanlış yapılandırılmış istemci uygulamalarına erişim izni verilmesini önlemek için önemlidir. Birden fazla OAuth 2.0 akışını destekliyorsanız response_type öğesinin code olduğunu da onaylayın.
  2. Kullanıcının hizmetinizde oturum açıp açmadığını kontrol edin. Kullanıcı oturum açmamışsa hizmetinizin oturum açma veya kaydolma akışını tamamlayın.
  3. Google'ın API'nize erişmek için kullanacağı bir yetkilendirme kodu oluşturun. Yetkilendirme kodu herhangi bir dize değeri olabilir ancak kullanıcıyı, jetonun istemcisini, kodun kullanım süresini ve kodun son kullanma tarihini benzersiz bir şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Genellikle yaklaşık 10 dakika sonra sona eren yetkilendirme kodları yayınlarsınız.
  4. redirect_uri parametresi tarafından belirtilen URL'nin aşağıdaki biçimde olduğunu doğrulayın: 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
  https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
  5. Kullanıcının tarayıcısını redirect_uri parametresi tarafından belirtilen URL'ye yönlendirin. Yönlendirme yaparken code ve state parametrelerini ekleyerek, oluşturduğunuz yetkilendirme kodunu ve değiştirilmemiş orijinal durum değerini ekleyin. Elde edilen URL'nin bir örneğini aşağıda görebilirsiniz: 
    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Jeton değişimi isteklerini işleme

Hizmetinizin jeton exchange uç noktası iki tür jeton değişiminden sorumludur:

  • Erişim jetonları ve yenileme jetonları için yetkilendirme kodlarını değiştirme
  • Erişim jetonları için exchange yenileme jetonları

Jeton değişimi istekleri aşağıdaki parametreleri içerir:

Jeton değişimi uç nokta parametreleri
client_id İstek kaynağını Google olarak tanımlayan bir dize. Bu dize, sisteminizde Google’ın benzersiz tanımlayıcısı olarak kaydedilmelidir.
client_secret Hizmetiniz için Google'a kaydettiğiniz gizli dize.
grant_type Alınan jetonun türü. authorization_code veya refresh_token şeklindedir.
code grant_type=authorization_code olduğunda, bu parametre Google'ın oturum açma veya jeton değişimi uç noktanızdan aldığı koddur.
redirect_uri grant_type=authorization_code olduğunda bu parametre, ilk yetkilendirme isteğinde kullanılan URL'dir.
refresh_token grant_type=refresh_token olduğunda bu parametre, Google'ın jeton takas uç noktanızdan aldığı yenileme jetonudur.

Erişim jetonları ve yenileme jetonları için yetkilendirme kodlarını değiştirme

Kullanıcı oturum açıp yetkilendirme uç noktanız Google'a kısa ömürlü bir yetkilendirme kodu döndürdükten sonra Google, jeton Exchange uç ucunuza bir erişim jetonu ve yenileme jetonuyla yetkilendirme kodu değişimi için bir istek gönderir.

Bu isteklerde grant_type değeri authorization_code, code değeri ise daha önce Google'a verdiğiniz yetkilendirme kodunun değeridir. Aşağıda, bir erişim jetonu ve yenileme jetonu için yetkilendirme kodu değişimi isteği örneği verilmiştir:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

Bir erişim jetonu ve yenileme jetonu için yetkilendirme kodları alışverişi yapmak üzere, jeton değişimi uç noktanız aşağıdaki adımları yürüterek POST isteklerine yanıt verir:

  1. client_id öğesinin, istek kaynağını yetkili bir kaynak olarak tanımladığını ve client_secret değerinin beklenen değerle eşleştiğini doğrulayın.
  2. Yetkilendirme kodunun geçerli olduğunu, geçerlilik süresinin dolmadığını ve istekte belirtilen istemci kimliğinin, yetkilendirme koduyla ilişkilendirilen istemci kimliğiyle eşleştiğini doğrulayın.
  3. redirect_uri parametresi tarafından belirtilen URL'nin, ilk yetkilendirme isteğinde kullanılan değerle aynı olduğunu onaylayın.
  4. Yukarıdaki ölçütlerin tamamını doğrulayamıyorsanız gövde olarak {"error": "invalid_grant"} ile bir HTTP 400 Hatalı İstek hatası döndürün.
  5. Aksi takdirde, yenileme jetonu ve erişim jetonu oluşturmak için yetkilendirme kodundaki kullanıcı kimliğini kullanın. Bu jetonlar herhangi bir dize değeri olabilir. Ancak jeton, kullanıcıyı ve jetonun ait olduğu istemciyi benzersiz bir şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Erişim jetonları için, jetonun geçerlilik süresini de kaydedin. Bu, genellikle jetonun düzenlenmesinin ardından bir saat sürer. Yenileme jetonlarının süresi dolmaz.
  6. HTTPS yanıtının gövdesinde aşağıdaki JSON nesnesini döndürün: 
    {
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"refresh_token": "REFRESH_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}

Google, erişim jetonunu ve yenileme jetonunu kullanıcı için depolar ve erişim jetonunun geçerlilik süresini kaydeder. Erişim jetonunun süresi dolduğunda Google, jeton jetonunuzu yeni bir erişim jetonu almak için yenileme jetonunu kullanır.

Erişim jetonları için exchange yenileme jetonları

Bir erişim jetonunun süresi dolduğunda Google, jeton Exchange uç noktanıza yeni bir erişim jetonu için yenileme jetonu karşılığında bir istek gönderir.

Bu isteklerde grant_type değeri refresh_token, refresh_token değeri ise daha önce Google'a verdiğiniz yenileme jetonunun değeridir. Aşağıda, bir erişim jetonuyla yenileme jetonu alma isteğinin bir örneği verilmiştir:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

Bir erişim jetonuyla yenileme jetonunu değiştirmek için jeton değişimi uç noktanız aşağıdaki adımları uygulayarak POST isteklerine yanıt verir:

  1. client_id öğesinin, isteğin kaynağını Google olarak tanımladığını ve client_secret değerinin beklenen değerle eşleştiğini doğrulayın.
  2. Yenileme jetonunun geçerli olduğunu ve istekte belirtilen istemci kimliğinin, yenileme jetonuyla ilişkilendirilen istemci kimliğiyle eşleştiğini doğrulayın.
  3. Yukarıdaki ölçütlerin tamamını doğrulayamıyorsanız gövde olarak {"error": "invalid_grant"} ile bir HTTP 400 Hatalı İstek hatası döndürün.
  4. Aksi takdirde, erişim jetonu oluşturmak için yenileme jetonundaki kullanıcı kimliğini kullanın. Bu jetonlar herhangi bir dize değeri olabilir. Ancak bu jeton, kullanıcıyı ve jetonun ait olduğu istemciyi benzersiz bir şekilde temsil etmeli ve tahmin edilebilir olmamalıdır. Erişim jetonları için, jetonun geçerlilik süresini de (genellikle jetonu vermenizin ardından bir saat) kaydedin.
  5. HTTPS yanıtının gövdesinde aşağıdaki JSON nesnesini döndürün: 
    {
"token_type": "Bearer","access_token": "ACCESS_TOKEN","expires_in": SECONDS_TO_EXPIRATION
}

Kullanıcı bilgisi isteklerini işleme

Userinfo uç noktası, bağlı kullanıcıyla ilgili hak talepleri döndüren OAuth 2.0 korumalı bir kaynaktır. Aşağıdaki kullanım alanları hariç, kullanıcı bilgileri uç noktasını uygulama ve barındırma isteğe bağlıdır:

Erişim jetonu jeton uç noktanızdan başarıyla alındıktan sonra Google, bağlı kullanıcıyla ilgili temel profil bilgilerini almak için kullanıcı bilgileri uç noktanıza bir istek gönderir.

kullanıcı bilgisi uç nokta isteği üstbilgileri
Authorization header Taşıyıcı türünün erişim jetonu.

Örneğin, kullanıcı bilgisi uç noktanız https://myservice.example.com/userinfo adresinde kullanılabiliyorsa bir istek aşağıdaki gibi görünebilir:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

Kullanıcı bilgisi uç noktanızın istekleri işlemesi için aşağıdaki adımları uygulayın:

  1. Erişim jetonunu Yetkilendirme başlığından çıkarın ve erişim jetonuyla ilişkilendirilmiş kullanıcı için bilgileri döndürün.
  2. Erişim jetonu geçersizse WWW-Authenticate Yanıt Başlığı ile HTTP 401 Yetkisiz hatası döndürün. Kullanıcı bilgisi hata yanıtı örneği: 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    Bağlantı oluşturma işlemi sırasında 401 Yetkilendirilmediyse veya başka bir hata yanıtı döndürülürse hata kurtarılamaz. Alınan jeton silinir ve kullanıcının bağlantı işlemini yeniden başlatması gerekir.

  3. Erişim jetonu geçerliyse HTTPS yanıtının gövdesinde aşağıdaki JSON nesnesiyle HTTP 200 yanıtını döndürün: 

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
    Kullanıcı bilgisi uç noktanız bir HTTP 200 başarı yanıtı döndürürse alınan jeton ve hak talepleri kullanıcının Google hesabına kaydedilir.

    kullanıcı bilgisi uç nokta yanıtı
    sub Sisteminizdeki kullanıcıyı tanımlayan benzersiz bir kimlik.
    email Kullanıcının e-posta adresi.
    given_name İsteğe bağlı: Kullanıcının adı.
    family_name İsteğe bağlı: Kullanıcının soyadı.
    name İsteğe bağlı: Kullanıcının tam adı.
    picture İsteğe bağlı: Kullanıcının profil resmi.
Önceki
Geliştirici kontrol listesi
Sonraki
Actions projesi oluşturma