Admin Settings API'ye genel bakış

Admin Settings API, Google Workspace alanlarının yöneticilerinin alanlarının ayarlarını Google Data API feed'leri biçiminde almasına ve değiştirmesine olanak tanır.

Bu alan ayarları, Google Workspace Yönetici Konsolu'nda bulunan birçok özelliği içerir. Bu API'nin kullanım örnekleri arasında özel bir kontrol paneli oluşturma veya Google Workspace alanlarını mevcut eski bir ortama entegre etme yer alır.

Yönetici Ayarları API'si, Google Veri API'leri protokolünü uygular. Google Veri API'leri, Atom Yayınlama Protokolü (AtomPub) yayınlama ve düzenleme modeline uygundur. AtomPub HTTP istekleri, web hizmetleri için Temsili Durum Aktarımı (RESTful) tasarım yaklaşımını kullanır. Daha fazla bilgi için Google Veri API'leri Geliştirici Kılavuzu'na bakın.

Kitle

Bu belge, Google Workspace alanlarıyla ilgili bilgileri değiştirebilen ve alabilen istemci uygulamaları yazmak isteyen geliştiriciler için hazırlanmıştır. Bu dokümanda, ham XML ve HTTP kullanılarak yapılan temel Yönetici Ayarları API etkileşimleriyle ilgili örnekler verilmektedir.

Bu belgede, Google Veri API'si protokolünün temel kavramlarını bildiğiniz ve Google Workspace Yönetici Konsolu'nu kullandığınız varsayılır. Yönetici Konsolu hakkında daha fazla bilgi için Yönetici Konsolu'nu kullanma başlıklı makaleyi inceleyin.

Başlayın

Yönetici Ayarları API'sini kullanmaya başlamak için önce hesabınızı ayarlayın.

Hesap oluştur

Yönetici Ayarları API'si, Google Workspace hesapları için etkinleştirilmiştir. Test amacıyla Google Workspace hesabına kaydolun. Yönetici Ayarları hizmeti Google Hesapları'nı kullandığından Google Workspace alanında zaten bir hesabınız varsa hazırsınız demektir.

Not: Alan ayarlarınızı Yönetici Ayarları API'sini kullanarak yapılandırın ve kullanıcılarınızın e-posta ayarlarını yapılandırmak için E-posta Ayarları API'sini kullanın.

Admin Settings API özet akışı türleri hakkında

Admin Settings API, aşağıdaki alan ayarları kategorilerini yönetmenize olanak tanır:

Tek Oturum Açma ayarları

SAML tabanlı tek oturum açma (TOA), kullanıcıların hem Google Workspace'te barındırılan hizmetler hem de kuruluşunuzda barındırabileceğiniz diğer hizmetler için aynı giriş ve şifreyi kullanmasına olanak tanır. Özellikle TOA kullanılırken Google Workspace gibi barındırılan bir web uygulaması, kullanıcılar oturum açtığında kimliklerini doğrulamak için kullanıcıları kuruluşunuzun kimlik sağlayıcısına yönlendirir. Ayrıntılı bilgi için Google Workspace için SAML tabanlı TOA'yı anlama başlıklı makaleyi inceleyin.

TOA'yı yapılandırmak için Google Workspace hizmetinin, kullanıcılarınızın giriş bilgilerini depolayan kimlik sağlayıcıyla iletişim kurması için gerekli bilgileri girmeniz ve kullanıcıların giriş yapma, çıkış yapma ve şifrelerini değiştirme işlemlerini gerçekleştirmek için yönlendirileceği bağlantıları ayarlamanız gerekir. Yönetici Ayarları API'si, bu ayarları programatik olarak güncellemenize ve almanıza olanak tanır. Google, bu TOA isteğini kimlik sağlayıcınızla doğrularken ve özel anahtar SAML yanıtının ağ iletimi sırasında değiştirilmediğini doğrulamak için oluşturduğunuz genel anahtarı kullanır.

TOA ayarlarının kullanımıyla ilgili kısa ve API'ye özel bir özet için kimlik sağlayıcınızdan ortak anahtar sertifikanızı alın, ortak anahtarı Google'a kaydedin ve SAML tabanlı TOA sorgu ayarlarınızı yapın. Hata mesajları için TOA sorunlarını giderme başlıklı makaleyi inceleyin:

• Anahtarlarınızı oluşturun: Kimlik sağlayıcınızla birlikte DSA veya RSA algoritmalarını kullanarak bir dizi ortak ve özel anahtar oluşturun. Ortak anahtar, X.509 biçimli bir sertifikadadır. SAML tabanlı tek oturum açma imzalama anahtarları hakkında daha fazla bilgi için Google Workspace Tek Oturum Açma Hizmeti İçin Anahtar ve Sertifika Oluşturma başlıklı makaleyi inceleyin.
• Google'a kaydolma: Ortak anahtar sertifikanızı Google'a kaydetmek için Admin Settings API'nin tek oturum açma ayarlarını kullanın.
• TOA ayarlarınızı yapın: Alanın kimlik sağlayıcısının sunucularıyla iletişim kurmak için kullanılan ayarları yapılandırmak üzere Yönetici Ayarları API'sinin Tek Oturum Açma ayarlarını kullanın.

Not: Bazı POP/IMAP e-posta istemcileri gibi web tabanlı oturum açma akışı kullanmayan protokollerde kullanıcılar doğrudan Google Workspace kullanıcı adları ve şifreleriyle oturum açar.

Ağ geçidi ayarları

Bu feed, alan yöneticilerinin alanları için e-posta yönlendirmesini kontrol etmesine olanak tanır.

E-posta yönlendirme işlemleri, yöneticilerin alan düzeyinde e-posta yönlendirme ayarlarını belirtmesine olanak tanır. Bu, Yönetici Konsolu'nun Gmail ayarlarındaki e-posta yönlendirme işlevine benzer. Daha fazla bilgi için E-posta yönlendirmesi ve E-posta yönlendirme özelliğinin ikili dağıtım yapılandırması başlıklı makaleleri inceleyin.

Yönetici Ayarları API'si XML isteği ve yanıtı örneği

Bu belgede, ham XML ve HTTP kullanılarak yapılan temel Yönetici Ayarları API istekleri ve yanıtlarıyla ilgili kod örnekleri verilmektedir. Bu alan varsayılan dili örneğinde, her işlem için ortak olan bir istek ve yanıt girişinin gövdesine ait tam XML ve HTTP söz dizimi gösterilmektedir:

Alan adının giden e-posta ağ geçidi ayarını değiştirmek için ağ geçidi feed'i URL'sine bir HTTP PUT isteği gönderin:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

Alan adının varsayılan dili PUT AtomPub entry XML'si için istek:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
  xmlns:apps='http://schemas.google.com/apps/2006'>
  <apps:property name='smartHost' value='smtp.out.domain.com' />
  <apps:property name='smtpMode' value='SMTP' />
</atom:entry>

İşleme özgü özellikler ve değerler hariç olmak üzere atom:property öğeleri, almak veya güncellemek istediğiniz bir özellik hakkında bilgi içeren tek bir anahtar/değer çiftini temsil eder. Bunlar tüm Yönetici Ayarları API'si istek gövdelerinde ortaktır.

Alan varsayılan dil yanıtı entry öğesi, tüm Yönetici Ayarları API yanıt gövdelerinde ortak olan XML söz dizimiyle birlikte smartHost ve smtpMode özelliklerini döndürür:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<id>https://apps-apis.google.com/a/feeds/domain/2.0/domainName/email/gateway</id>
<updated>2008-12-17T23:59:23.887Z</updated>
<link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/domain/
  2.0/domainName/email/gateway'/>
<link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/domain/
  2.0/domainName/email/gateway'/>
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</entry>

Tek oturum açma ayarlarını yönetme

Google Workspace Tek Oturum Açma (TOA) özelliği, kullanıcıların birden fazla hizmete giriş yapmasına olanak tanır. Kullanıcılar, yalnızca bir kez giriş ve şifre girmek zorundadır. Bu şifre, Google Workspace tarafından değil, alanın kimlik sağlayıcısı tarafından saklanır. Daha fazla bilgi için Yardım Merkezi'nin SSO sayfasına bakın. Aşağıdaki bölümlerde, Tek Oturum Açma ayarları için kullanılan XML biçimi gösterilmektedir.

Tek oturum açma ayarlarını alma

Tek oturum açma ayarlarını almak için TOA genel feed URL'sine bir HTTP GET isteği gönderin ve Yönetici Ayarları hizmetinde kimlik doğrulama bölümünde açıklandığı gibi bir Authorization başlığı ekleyin. Hata mesajları için SSO ile ilgili sorunları giderme başlıklı makaleyi inceleyin:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general

Bu işlemin istek gövdesinde parametre yok.

Başarılı bir yanıt, alanın SSO ayarlarını içeren bir AtomPub feed'iyle birlikte HTTP 200 OK durum kodu döndürür.

GET yanıtı XML'si samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist ve useDomainSpecificIssuer özelliklerini döndürür:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon'/>
...
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout'/>
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword'/>
<apps:property name='enableSSO' value='true'/>
<apps:property name='ssoWhitelist' value='CIDR formatted IP address'/>
<apps:property name='useDomainSpecificIssuer' value='false'/>
</entry>

Özellikler şunlardır:

samlSignonUri

Google Workspace'in kullanıcı kimlik doğrulaması için SAML isteğini gönderdiği kimlik sağlayıcının URL'si.

samlLogoutUri

Kullanıcılar web uygulamasından çıktıklarında yönlendirilecekleri adres.

changePasswordUri

Kullanıcılar, web uygulaması için TOA şifrelerini değiştirmek istediklerinde yönlendirilecekleri adres.

enableSSO

Bu alan için SAML tabanlı TOA'yı etkinleştirir. Daha önce TOA ayarlarını yapılandırdıysanız ve ardından enableSSO ayarını enableSSO=false olarak belirlediyseniz daha önce girdiğiniz ayarlar yine de kaydedilir.

ssoWhitelist

ssoWhitelist, Sınıfsız Alanlar Arası Yönlendirme (CIDR) biçiminde bir ağ maskesi IP adresidir. ssoWhitelist, hangi kullanıcıların TOA kullanarak, hangi kullanıcıların ise Google Workspace hesap kimlik doğrulama sayfasını kullanarak oturum açacağını belirler. Maske belirtilmediğinde tüm kullanıcılar TOA kullanarak oturum açar. Daha fazla bilgi için Ağ maskeleri nasıl çalışır? başlıklı makaleyi inceleyin.

useDomainSpecificIssuer

Kimlik sağlayıcıya gönderilen SAML isteğinde alana özel bir yayıncı kullanılabilir. Çoğu TOA dağıtımı için gerekli olmasa da bu özellik, birden fazla alt alan adıyla tüm bir kuruluşu kimlik doğrulamak için tek bir kimlik sağlayıcı kullanan büyük şirketlerde faydalıdır. Belirli bir alan yayıncısının verilmesi, istekle hangi alt alan adının ilişkilendirileceğini belirler. Daha fazla bilgi için SAML isteğindeki Issuer öğesi nasıl çalışır? başlıklı makaleyi inceleyin.

İsteğiniz herhangi bir nedenle başarısız olursa farklı bir durum kodu döndürülür. Google Veri API'si durum kodları hakkında daha fazla bilgi için HTTP durum kodları konusuna bakın.

Tek oturum açma ayarlarını güncelleme

Bir alanın TOA ayarlarını güncellemek için önce Tek Oturum Açma ayarlarını al işlemini kullanarak TOA ayarlarını alın, değiştirin ve ardından TOA feed URL'sine bir PUT isteği gönderin. <id> değerinin, güncellenen girişinizde mevcut girişin <id> ile tam olarak eşleştiğinden emin olun. Authenticating to the Admin Settings API service (Yönetici Ayarları API hizmetinde kimlik doğrulama) bölümünde açıklandığı gibi bir Authorization üstbilgisi ekleyin. Hata mesajları için SSO ile ilgili sorunları giderme başlıklı makaleyi inceleyin.

Tek oturum açma ayarlarını güncellerken TOA genel feed'ine bir HTTP PUT isteği gönderin. URL:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general

PUT isteğinin XML metni:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='enableSSO' value='false' />
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon' />
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout' />
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword' />
<apps:property name='ssoWhitelist' value='127.0.0.1/32' />
<apps:property name='useDomainSpecificIssuer' value='false'/>
</atom:entry>

Başarılı bir yanıt, HTTP 200 OK durum kodunun yanı sıra SSO ayarlarını içeren bir AtomPub feed'i döndürür.

PUT yanıtı XML'si:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon'/>
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout'/>
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword'/>
<apps:property name='enableSSO' value='false'/>
<apps:property name='ssoWhitelist' value='127.0.0.1/32'/>
<apps:property name='useDomainSpecificIssuer' value='false'/>
</entry>

İsteğiniz herhangi bir nedenle başarısız olursa farklı bir durum kodu döndürülür. Google Veri API'si durum kodları hakkında daha fazla bilgi için HTTP durum kodları konusuna bakın.

Hedef müşterinin hassas işlemler için çok taraflı onayı etkinleştirdiği durumlarda tek oturum açma ayarlarında değişiklik yapılmasına izin verilmez. İstekler errorCode="1811" ve reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval" ile başarısız olur.

Tek Oturum Açma imzalama anahtarını alma

Tek oturum açma imzalama anahtarını almak için TOA imzalama anahtarı feed URL'sine bir HTTP GET isteği gönderin ve Yönetici Ayarları hizmetinde kimlik doğrulama bölümünde açıklandığı gibi bir Authorization üstbilgisi ekleyin. Hata mesajları için TOA sorunlarını giderme başlıklı makaleyi inceleyin:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey

Bu işlemin istek gövdesinde parametre yok.

Başarılı bir yanıt, imzalama anahtarını içeren bir AtomPub feed'iyle birlikte HTTP 200 OK durum kodu döndürür.

GET yanıtı XML'si, signingKey özelliğini döndürür:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='signingKey' value='yourBase64EncodedPublicKey'/>
</entry>

İsteğiniz herhangi bir nedenle başarısız olursa farklı bir durum kodu döndürülür. Google Veri API'si durum kodları hakkında daha fazla bilgi için HTTP durum kodları konusuna bakın.

Tek oturum açma imzalama anahtarını güncelleme

Bir alanın TOA imzalama anahtarını güncellemek için önce Tek Oturum Açma imzalama anahtarını al işlemini kullanarak imzalama anahtarını alın, değiştirin ve ardından TOA imzalama anahtarı feed'i URL'sine bir PUT isteği gönderin. Güncellenen girişinizdeki <id> değerinin, mevcut girişin <id> değeriyle tam olarak eşleştiğinden emin olun. SAML tabanlı tek oturum açma imzalama anahtarları hakkında daha fazla bilgi için Google Workspace Tek Oturum Açma Hizmeti için Anahtar ve Sertifika Oluşturma başlıklı makaleyi inceleyin.

Tek oturum açma imzalama anahtarı güncellenirken TOA imzalama anahtarı feed URL'sine bir HTTP PUT isteği gönderin:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey

PUT isteği XML'si:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='signingKey' value='yourBase64EncodedPublicKey'/>
</atom:entry>

Not: Bu istek için signingKey özelliği gereklidir.

Hedef müşterinin hassas işlemler için çok taraflı onayı etkinleştirdiği durumlarda tek oturum açma ayarlarında değişiklik yapılmasına izin verilmez. İstekler errorCode="1811" ve reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval" ile başarısız olur.

E-posta ağ geçidini yönetme

Giden e-posta ağ geçidi bölümünde, Admin Settings API'nin alanınızdaki kullanıcılardan gelen postaların giden yönlendirmesini nasıl desteklediği gösterilmektedir.

Giden e-posta ağ geçidi ayarlarını alma

Giden e-posta ağ geçidi ayarlarını almak için ağ geçidi feed URL'sine bir HTTP GET isteği gönderin ve Yönetici Ayarları hizmetinde kimlik doğrulama bölümünde açıklandığı gibi bir Authorization üstbilgisi ekleyin:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

Bu işlemin istek gövdesinde parametre yok.

Not: Google Workspace giden ağ geçidi özelliğini kullanmak için uygun bir Google Workspace sürümüne sahip olmanız gerekir.

Başarılı bir yanıt, e-posta ağ geçidi durum bilgilerini içeren bir AtomPub feed'iyle birlikte HTTP 200 OK durum kodu döndürür.

GET yanıtı, smartHost ve smtpMode özelliklerini döndürür. Bu özellikler hakkında daha fazla bilgi için Giden e-posta ağ geçidi ayarlarını güncelleme başlıklı makaleyi inceleyin.

Olası bir yanıt örneği:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='smartHost' value='smtpout.domain.com'/>
<apps:property name='smtpMode' value='SMTP'/>
</entry>

İsteğiniz herhangi bir nedenle başarısız olursa farklı bir durum kodu döndürülür. Google Veri API'si durum kodları hakkında daha fazla bilgi için HTTP durum kodları konusuna bakın.

Giden e-posta ağ geçidi ayarlarını güncelleme

Bir alanın giden e-posta ağ geçidi ayarını güncellemek için ağ geçidi feed'i URL'sine bir HTTP PUT isteği gönderin:

https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway

Not: Google Workspace giden ağ geçidi özelliğini kullanmak için uygun bir Google Workspace sürümüne sahip olmanız gerekir.

PUT isteği XML'si:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</atom:entry>

İstek özellikleri şunlardır:

smartHost

SMTP sunucunuzun IP adresi veya ana makine adı. Google Workspace, giden postaları bu sunucuya yönlendirir.

smtpMode

Varsayılan değer SMTP'dir. SMTP_TLS adlı başka bir değer, ileti teslim edilirken TLS ile bağlantıyı güvenli hale getirir.

Not: Google Workspace'ten gönderilen iletilen e-postaları yapılandırmak için posta aktarım aracınızın talimatlarını uygulayın.

Başarılı bir yanıt, e-posta ağ geçidi ayarları durumunu içeren AtomPub feed'iyle birlikte bir HTTP 200 OK durum kodu döndürür.

Not: Yaptığınız değişikliklerden sonra ağ geçidiniz üzerinden gönderilen giden postaların çalıştığını doğrulamak için Google Workspace'ten alanınızın dışındaki bir kullanıcıya e-posta gönderin.

İsteğiniz herhangi bir nedenle başarısız olursa farklı bir durum kodu döndürülür. Google Veri API'si durum kodları hakkında daha fazla bilgi için HTTP durum kodları konusuna bakın.

Uç noktalar 31 Ekim 2018'de kullanımdan kaldırılacak

Bu duyuru kapsamında aşağıdaki uç noktaların desteğini sonlandırdık. Bu özellikler 31 Ekim 2018'de kullanımdan kaldırıldı ve artık kullanılamıyor.

• https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/defaultLanguage
• https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/organizationName
• https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/currentNumberOfUsers
• https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/maximumNumberOfUsers
• https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/supportPIN
• https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/customerPIN
• https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/adminSecondaryEmail
• https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/edition
• https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/creationTime
• https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/countryCode
• https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/appearance/customLogo
• https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/verification/mx