Admin Settings API'ye genel bakış

Admin Settings API'si, 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 adı ayarları, Google Workspace Yönetici Konsolu'nda bulunan özelliklerin birçoğunu içerir. Bu API'nin kullanım örnekleri arasında özel kontrol paneli oluşturma veya Google Workspace alanlarını mevcut eski bir ortama entegre etme yer alır.

Admin Settings API, Google Data API protokolünü uygular. Google Data API, Atom Yayınlama Protokolü (AtomPub) yayınlama ve düzenleme modeline uygundur. AtomPub HTTP istekleri, web hizmetlerine Representational Set Transfer (RESTful) tasarım yaklaşımını kullanır. Daha fazla bilgi için Google Veri Geliştirici Kılavuzu'na bakın.

Kitle

Bu doküman, Google Workspace alanlarını değiştirebilen ve bilgi alabilen istemci uygulamaları yazmak isteyen geliştiricilere yöneliktir. Bu sayfada, ham XML ve HTTP kullanan temel Admin Settings API etkileşimleriyle ilgili örnekler yer almaktadır.

Bu dokümanda, Google Data API protokolü ile ilgili genel fikirleri anladığınız ve Google Workspace Yönetici Konsolu hakkında bilgi sahibi olduğunuz varsayılmaktadır. Yönetici konsolu hakkında daha fazla bilgi edinmek için Yönetici Konsolunuzu kullanma başlıklı makaleye göz atın.

Başlarken

Hesap oluşturma

Admin Settings API, Google Workspace hesapları için etkinleştirildi. Test amacıyla bir Google Workspace hesabına kaydolun. Yönetici Ayarları hizmeti, Google Hesaplarını kullanır. Dolayısıyla bir Google Workspace alanında hesabınız varsa hazırsınız demektir.

Admin Settings API feed türleri hakkında

Admin Settings API'si aşağıdaki alan adı 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 tarafından barındırılan hizmetler hem de kuruluşunuzda barındırıyor olabileceğ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ı, giriş yaptıklarında kullanıcıların 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 yapılandırması, kullanıcılarınızın giriş bilgilerini depolayan kimlik sağlayıcıyla iletişim kurmak için Google Workspace hizmetine gerekli bilgilerin girilmesinin yanı sıra kullanıcıların giriş yapmak, çıkış yapmak ve şifrelerini değiştirmek için yönlendirilmeleri gereken bağlantıları ayarlamayı içerir. Admin Settings API, bu ayarları programatik olarak güncellemenize ve almanıza olanak tanır. Google, kimlik sağlayıcınızdaki bu TOA isteğini ve özel anahtar SAML yanıtının ağ iletimi sırasında değiştirilmediğini doğrulamak için oluşturduğunuz ortak anahtarı kullanır.

TOA ayarlarını kullanmayla ilgili API'ye özel kısa 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ı ayarlayın. Hata mesajları için TOA sorunlarını giderme sayfasına göz atın:

  • Anahtarlarınızı oluşturma: Kimlik sağlayıcınızla, DSA veya RSA algoritmalarını kullanarak bir dizi genel ve özel anahtar oluşturun. Ortak anahtar, X.509 biçiminde bir sertifikadır. SAML tabanlı Tek Oturum Açma imzalama anahtarları hakkında daha fazla bilgi edinmek için Google Workspace Tek Oturum Açma Hizmeti için Anahtar ve Sertifika Oluşturma başlıklı makaleyi inceleyin.
  • Google'a kaydolun -- 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 Admin Settings API'nin Tek Oturum Açma ayarlarını kullanın.

Ağ geçidi ve yönlendirme ayarları

Bu özet akışı, alan yöneticilerinin alanları için e-posta yönlendirmesini denetlemelerine 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 işlev, Yönetici konsolunun Gmail ayarlarındaki e-posta yönlendirme işlevine benzer. Daha fazla bilgi edinmek için E-posta yönlendirmesi ve e-posta yönlendirme özelliğinin ikili dağıtım yapılandırması sayfalarına göz atın.

Admin Settings API XML isteği ve yanıtı örneği

Bu dokümanda, ham XML ve HTTP kullanan temel Admin Settings API istekleri ve yanıtlarının kod örnekleri sunulmaktadır. Bu alan adı varsayılan dil örneği, her işlemde ortak olan, istek ve yanıt girişi gövdesine ilişkin tam XML ve HTTP söz dizimini göstermektedir:

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

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

PUT alan adı için AtomPub entry isteğindeki varsayılan dil:

<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 özel özellikler ve değerler haricinde atom:property öğeleri, almak veya güncellemek istediğiniz bir mülk hakkında bilgi içeren tek bir anahtar/değer çiftini temsil eder. Bunlar tüm Admin Settings API istek gövdelerinde ortaktır.

Alan adı varsayılan dil yanıtı entry öğesi, tüm Admin Settings 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 özelliği (TOA), kullanıcıların bir kez giriş yaparken birden çok hizmete giriş yapmalarına olanak tanı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 TOA sayfasına göz atı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ı alınıyor

Tek Oturum Açma ayarlarını almak için TOA genel feed URL'sine bir HTTP GET gönderin ve Yönetici Ayarları hizmetinde kimlik doğrulama başlıklı makalede açıklandığı gibi bir Authorization üstbilgisi ekleyin. Hata mesajları için TOA sorunlarını giderme sayfasına göz atın:

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 TOA 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>

Tesisler şunları içerir:

samlSignonUri
Google Workspace'in, kullanıcı kimlik doğrulaması için SAML isteğini gönderdiği kimlik sağlayıcı URL'si.
samlLogoutUri
Kullanıcıların web uygulamasından çıkış yaptıklarında gönderileceği adres.
changePasswordUri
Web uygulaması için TOA şifrelerini değiştirmek istediklerinde kullanıcıların gönderileceği adres.
enableSSO
Bu alan için SAML tabanlı TOA'yı etkinleştirir. Daha önce TOA ayarlarınızı yapılandırdıysanız ve daha sonra enableSSO ayarını enableSSO=false olarak belirlediyseniz önceden girdiğiniz ayarlar kayıtlı halde kalır.
ssoWhitelist
ssoWhitelist, Sınıfsız Alanlar Arası Yönlendirme (CIDR) biçimindeki bir ağ maskesi IP adresidir. ssoWhitelist, hangi kullanıcıların TOA kullanarak giriş yaptığını ve hangi kullanıcıların Google Workspace hesap kimlik doğrulama sayfasını kullanarak giriş yapacağını belirler. Maske belirtilmezse tüm kullanıcılar TOA kullanarak giriş yapar. Daha fazla bilgi için Ağ maskeleri nasıl çalışır? başlıklı makaleye bakın.
useDomainSpecificIssuer
Kimlik sağlayıcıya gönderilen SAML isteğinde, alana özgü bir yayıncı kullanılabilir. Çoğu TOA dağıtımı için gerekli olmasa da bu özellik, birden çok alt alan adıyla kuruluşun tamamında kimlik doğrulaması yapmak için tek bir kimlik sağlayıcı kullanan büyük şirketlerde kullanışlıdır. Belirli bir alanı veren kuruluş, istekle ilişkilendirilecek alt alan adını belirler. Daha fazla bilgi için Nasıl SAML isteğindeki Sertifikayı veren öğ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 Data API durum kodları hakkında daha fazla bilgi için HTTP durum kodları başlıklı makaleye bakın.

Tek Oturum Açma ayarlarını güncelleme

Bir alan adının TOA ayarlarını güncellemek için öncelikle Retrieving Single Sign-On settings (Tek Oturum Açma ayarlarını alma) işlemini kullanarak TOA ayarlarını alın, değiştirin ve ardından TOA feed'inin URL'sine bir PUT isteği gönderin. Güncellenen girişinizdeki <id> değerinin, mevcut girişin <id> değeri ile tam olarak eşleştiğinden emin olun. Admin Settings API hizmetinde kimlik doğrulama bölümünde açıklandığı şekilde bir Authorization üstbilgisi ekleyin. Hata mesajları için TOA sorunlarını giderme sayfasına göz atın.

Tek Oturum Açma ayarlarını güncellerken TOA genel feed URL'sine bir HTTP PUT gönderin:

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

PUT isteğinin XML gövdesi:

<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, TOA ayarlarını içeren bir AtomPub feed'iyle birlikte HTTP 200 OK durum kodu döndürür.

PUT yanıt XML'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='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 Data API durum kodları hakkında daha fazla bilgi için HTTP durum kodları başlıklı makaleye bakın.

Tek Oturum Açma imzalama anahtarını alma

Tek Oturum Açma imzalama anahtarını almak için TOA imzalama anahtarı feed'i URL'sine bir HTTP GET gönderin ve Yönetici Ayarları hizmetinden kimlik doğrulama başlıklı makalede açıklandığı gibi bir Authorization üstbilgisi ekleyin. Hata mesajları için TOA sorunlarını giderme sayfasına göz atın:

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ı içeren bir AtomPub feed'iyle birlikte HTTP 200 OK durum kodu döndürür.

GET yanıt XML'i, 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 Data API durum kodları hakkında daha fazla bilgi için HTTP durum kodları başlıklı makaleye bakın.

Tek Oturum Açma imzalama anahtarını güncelleme

Bir alan adının TOA imzalama anahtarını güncellemek için öncelikle Tek Oturum Açma imzalama anahtarı alma işlemini kullanarak imzalama anahtarını alın, değiştirin ve ardından TOA imzalama anahtarı feed URL'sine bir PUT isteği gönderin. Güncellenen girişinizdeki <id> değerinin, mevcut girişin <id> değeri ile tam olarak eşleştiğinden emin olun. SAML tabanlı Tek Oturum Açma imzalama anahtarları hakkında daha fazla bilgi edinmek 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ını güncellerken TOA imzalama anahtarı feed URL'sine bir HTTP PUT gönderin:

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

PUT istek 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>

E-posta ağ geçidini ve yönlendirmesini yönetme

Giden e-posta ağ geçidi bölümünde Admin Settings API'nin alanınızdaki kullanıcıların postalarının giden yönlendirmesini nasıl desteklediği gösterilir. E-posta yönlendirme bölümünde, iletilerin başka bir posta sunucusuna nasıl yönlendirileceği gösterilir.

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

Giden e-posta ağ geçidi ayarlarını almak için ağ geçidi feed URL'sine bir HTTP GET gönderin ve Yönetici Ayarları hizmetiyle 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.

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 edinmek için Giden e-posta ağ geçidi ayarlarını güncelleme başlıklı makaleye bakın.

Olası bir yanıt örneği şu şekildedir:

<?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 Data API durum kodları hakkında daha fazla bilgi için HTTP durum kodları başlıklı makaleye bakın.

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

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

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

PUT istek 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. Başka bir değer olan SMTP_TLS, iletiyi teslim ederken TLS ile bağlantının güvenliğini sağlar.

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.

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

E-posta yönlendirme ayarlarını yönetme

İlk olarak bir XML isteği oluşturun:

<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='routeDestination' value='route-smtp.domain.com'/>
<apps:property name='routeRewriteTo' value='true'/>
<apps:property name='routeEnabled' value='true'/>
<apps:property name='bounceNotifications' value='true'/>
<apps:property name='accountHandling' value='can be either allAccounts | provisionedAccounts | unknownAccounts'/>
</atom:entry>

İstek özellikleri şunlardır:

routeDestination
Bu hedef, e-postanın yönlendirildiği SMTP-In posta sunucusunun ana makine adı veya IP adresidir. Ana makine adı veya IP adresi Google için çözümlenmelidir. Posta ana makinesi adlarıyla ilgili sorunları çözme hakkında daha fazla bilgi için E-posta yönlendirmeli pilot Google Workspace başlıklı makaleyi inceleyin.
routeRewriteTo
True (doğru) değerine ayarlanırsa iletinin SMTP zarfının to: alanı, hedef ana makine adı (kullanıcı@hedef ana makine adı) olarak değiştirilir ve ileti, hedef posta sunucusunda bu kullanıcı adresine teslim edilir. false ise e-posta, hedef posta sunucusundaki orijinal iletinin to: e-posta adresine (kullanıcı@orijinal ana makine adı) teslim edilir. Bu ayar, Yönetici konsolunun "SMTP zarfını değiştir" ayarına benzer. Daha fazla bilgi için E-posta yönlendirme için alan ayarları başlıklı makaleyi inceleyin.
routeEnabled
true ise e-posta yönlendirme işlevi etkinleştirilir. false ise işlev devre dışı bırakılır.
bounceNotifications
true ise, Google Workspace bir teslim işlemi başarısız olduğunda gönderene geri dönen bildirimler göndermek üzere etkinleştirilir.
accountHandling

Bu ayar, alandaki farklı kullanıcı türlerinin e-posta yönlendirmesinden nasıl etkileneceğini belirler:

  • allAccounts -- Tüm e-postaları bu hedefe teslim et.
  • provisionedAccounts - Kullanıcı Google Workspace'te mevcutsa postaları bu hedefe teslim edin.
  • unknownAccounts - Kullanıcı Google Workspace'te yoksa postaları bu hedefe dağıtır. Bu, Yönetici konsolundaki "Teslimat e-postası" ayarına benzer. Ön koşullar ve posta yönlendirmesinin nasıl kullanılacağı hakkında daha fazla bilgi edinmek için E-posta yönlendirme için alan adı ayarları başlıklı makaleyi inceleyin. ~ Bu isteği yayınlamak için e-posta yönlendirme feed'i URL'sine bir HTTP POST gönderin ve Yönetici Ayarları hizmetinde kimlik doğrulama başlıklı makalede açıklandığı gibi bir Authorization üstbilgisi ekleyin:

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

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

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

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

Bu duyuru kapsamında aşağıdaki uç noktaların desteğini sonlandırdık. Bu öneriler 31 Ekim 2018'de sonlandırılmıştır ve artık kullanılamamaktadır.

  • 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