Ringkasan Admin Settings API

Dengan Admin Settings API, administrator domain Google Workspace dapat mengambil dan mengubah setelan domain mereka dalam bentuk feed Google Data API.

Setelan domain ini menyertakan banyak fitur yang tersedia di konsol Admin Google Workspace. Contoh penggunaan API ini termasuk membuat panel kontrol kustom atau mengintegrasikan domain Google Workspace ke lingkungan lama yang sudah ada.

Admin Settings API menerapkan protokol Google Data API. Google Data API mematuhi model publikasi dan pengeditan Atom Publishing Protocol (AtomPub). Permintaan HTTP AtomPub menggunakan pendekatan desain Representational Set Transfer (RESTful) untuk layanan web. Untuk informasi selengkapnya, lihat Panduan Developer Data Google.

Audiens

Dokumen ini ditujukan untuk developer yang ingin menulis aplikasi klien yang dapat mengubah dan mengambil informasi tentang domain Google Workspace. Halaman ini memberikan contoh interaksi Admin Settings API dasar menggunakan XML mentah dan HTTP.

Dokumen ini mengasumsikan bahwa Anda memahami ide umum di balik protokol Google Data API, dan bahwa Anda sudah memahami konsol Admin Google Workspace. Untuk informasi selengkapnya tentang konsol Admin, lihat Menggunakan konsol Admin.

Memulai

Membuat akun

Admin Settings API diaktifkan untuk akun Google Workspace. Daftar ke akun Google Workspace untuk tujuan pengujian. Layanan Setelan Admin menggunakan Akun Google. Jadi, jika Anda sudah memiliki akun di domain Google Workspace, berarti Anda sudah siap.

Tentang jenis feed Admin Settings API

Admin Settings API memungkinkan Anda mengelola kategori setelan domain berikut:

Setelan Single Sign-On

Single Sign-On (SSO) berbasis SAML memungkinkan pengguna menggunakan login dan sandi yang sama untuk layanan yang dihosting Google Workspace serta layanan lain yang mungkin Anda hosting dalam organisasi Anda. Khususnya saat menggunakan SSO, aplikasi web yang dihosting, seperti Google Workspace, akan mengalihkan pengguna ke penyedia identitas organisasi Anda untuk mengautentikasi pengguna saat mereka login. Untuk mengetahui informasi selengkapnya, lihat Memahami SSO berbasis SAML untuk Google Workspace.

Mengonfigurasi SSO mencakup proses memasukkan informasi yang diperlukan agar layanan Google Workspace berkomunikasi dengan penyedia identitas yang menyimpan informasi login pengguna, serta menyiapkan link yang harus dituju pengguna untuk login, logout, dan mengubah sandi. Admin Settings API memungkinkan Anda memperbarui dan mengambil setelan ini secara terprogram. Google menggunakan kunci publik yang dibuat untuk memverifikasi permintaan SSO ini dengan penyedia identitas Anda dan bahwa respons SAML kunci pribadi tidak diubah selama transmisi jaringan.

Untuk ringkasan khusus API singkat tentang penggunaan setelan SSO, dapatkan sertifikat kunci publik dari penyedia identitas, daftarkan kunci publik ke Google, dan siapkan setelan kueri SSO berbasis SAML. Untuk pesan error, lihat Memecahkan masalah SSO:

  • Buat kunci Anda -- Dengan penyedia identitas Anda, buat serangkaian kunci publik dan pribadi menggunakan algoritma DSA atau RSA. Kunci publik dalam sertifikat berformat X.509. Untuk mengetahui informasi selengkapnya tentang kunci penandatanganan Single Sign-On berbasis SAML, lihat Membuat Kunci dan Sertifikat untuk Layanan Single Sign-On Google Workspace.
  • Daftar ke Google -- Gunakan setelan Single Sign-On Admin Settings API untuk mendaftarkan sertifikat kunci publik Anda dengan Google.
  • Menyiapkan setelan SSO Anda -- Gunakan setelan Single Sign-On pada Admin Settings API untuk mengonfigurasi setelan yang digunakan untuk komunikasi dengan server penyedia identitas domain.

Setelan gateway dan pemilihan rute

Feed ini memungkinkan administrator domain mengontrol pemilihan rute email untuk domain mereka.

Operasi perutean email memungkinkan administrator menentukan setelan perutean email tingkat domain. Hal ini serupa dengan fungsi pemilihan rute email di setelan Gmail konsol Admin. Untuk mengetahui informasi selengkapnya, lihat Pemilihan rute email dan konfigurasi fitur pengiriman ganda untuk fitur pemilihan rute email.

Contoh permintaan dan respons XML Admin Settings API

Dokumen ini memberikan contoh kode permintaan dan respons Admin Settings API dasar menggunakan XML mentah dan HTTP. Contoh bahasa default domain ini menunjukkan sintaksis XML dan HTTP lengkap untuk isi entri permintaan dan respons yang umum untuk setiap operasi:

Untuk mengubah setelan gateway email keluar domain, kirim HTTP PUT ke URL feed gateway:

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

XML permintaan PUT AtomPub entry default domain adalah:

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

Kecuali untuk properti dan nilai khusus operasi, elemen atom:property mewakili satu pasangan nilai kunci yang berisi informasi tentang properti yang ingin Anda ambil atau perbarui. Hal ini umum terjadi pada semua isi permintaan Admin Settings API.

Elemen entry respons bahasa default domain menampilkan properti smartHost dan smtpMode beserta sintaksis XML yang umum untuk semua isi respons Admin Settings API:

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

Mengelola setelan Single Sign-On

Fitur Single Sign-On (SSO) Google Workspace memungkinkan pengguna login ke beberapa layanan, tanpa harus memasukkan login dan sandi satu kali saja. Sandi ini disimpan oleh penyedia identitas domain, bukan oleh Google Workspace. Untuk mengetahui informasi selengkapnya, lihat halaman SSO Pusat Bantuan. Bagian berikut menunjukkan format XML yang digunakan untuk setelan Single Sign-On.

Mengambil setelan Single Sign-On

Untuk mengambil setelan Single Sign-On, kirim GET HTTP ke URL feed umum SSO, dan sertakan header Authorization seperti yang dijelaskan dalam Mengautentikasi ke layanan Setelan Admin. Dan, untuk pesan error, lihat Memecahkan masalah SSO:

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

Operasi ini tidak memiliki parameter dalam isi permintaan.

Respons yang berhasil akan menampilkan kode status HTTP 200 OK, beserta feed AtomPub dengan setelan SSO domain.

XML respons GET menampilkan properti samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist, dan useDomainSpecificIssuer:

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

Properti tersebut meliputi:

samlSignonUri
URL penyedia identitas tempat Google Workspace mengirimkan permintaan SAML untuk autentikasi pengguna.
samlLogoutUri
Alamat tujuan pengiriman pengguna saat mereka logout dari aplikasi web.
changePasswordUri
Alamat yang akan dituju pengguna saat mereka ingin mengubah sandi SSO untuk aplikasi web.
enableSSO
Mengaktifkan SSO berbasis SAML untuk domain ini. Jika Anda sebelumnya telah mengonfigurasi setelan SSO, kemudian Anda menetapkan enableSSO ke enableSSO=false, setelan yang telah Anda masukkan sebelumnya akan tetap disimpan.
ssoWhitelist
ssoDaftar yang diizinkan adalah alamat IP network mask dalam format Classless Inter-Domain Routing (CIDR). ssowhitelist menentukan pengguna mana yang login menggunakan SSO dan pengguna mana yang login menggunakan halaman autentikasi akun Google Workspace. Jika tidak ada mask yang ditentukan, semua pengguna akan login menggunakan SSO. Untuk mengetahui informasi selengkapnya, lihat Cara kerja network mask.
useDomainSpecificIssuer
Penerbit khusus domain dapat digunakan dalam permintaan SAML ke penyedia identitas. Meskipun tidak diperlukan untuk sebagian besar penerapan SSO, fitur ini berguna di perusahaan besar yang menggunakan satu penyedia identitas untuk mengautentikasi seluruh organisasi dengan beberapa subdomain. Memberikan penerbit domain tertentu akan menentukan subdomain yang akan dikaitkan dengan permintaan. Untuk informasi selengkapnya, lihat Bagaimana cara kerja elemen Penerbit di permintaan SAML?

Jika permintaan Anda gagal karena alasan tertentu, kode status yang berbeda akan ditampilkan. Untuk informasi selengkapnya tentang kode status Google Data API, lihat kode status HTTP.

Memperbarui setelan Single Sign-On

Untuk memperbarui setelan SSO domain, pertama-tama ambil setelan SSO menggunakan operasi Pengambilan setelan Single Sign-On, ubah, lalu kirim permintaan PUT ke URL feed SSO. Pastikan nilai <id> ada dalam entri yang diperbarui sama persis dengan <id> entri yang ada. Sertakan header Authorization seperti yang dijelaskan dalam artikel Mengautentikasi ke layanan Admin Settings API. Dan, untuk pesan error, lihat Memecahkan masalah SSO.

Saat memperbarui setelan Single Sign-On, kirim HTTP PUT ke URL feed umum SSO:

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

Isi XML permintaan PUT adalah:

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

Respons yang berhasil akan menampilkan kode status HTTP 200 OK, beserta feed AtomPub dengan setelan SSO.

XML respons PUT adalah:

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

Jika permintaan Anda gagal karena alasan tertentu, kode status yang berbeda akan ditampilkan. Untuk informasi selengkapnya tentang kode status Google Data API, lihat kode status HTTP.

Mengambil kunci penandatanganan Single Sign-On

Untuk mengambil kunci penandatanganan Single Sign-On, kirim GET HTTP ke URL feed kunci penandatanganan SSO, dan sertakan header Authorization seperti yang dijelaskan dalam Mengautentikasi ke layanan Setelan Admin. Dan, untuk pesan error, lihat Memecahkan masalah SSO:

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

Operasi ini tidak memiliki parameter dalam isi permintaan.

Respons yang berhasil akan menampilkan kode status HTTP 200 OK, beserta feed AtomPub dengan kunci penandatanganan.

XML respons GET menampilkan properti signingKey:

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

Jika permintaan Anda gagal karena alasan tertentu, kode status yang berbeda akan ditampilkan. Untuk informasi selengkapnya tentang kode status Google Data API, lihat kode status HTTP.

Memperbarui kunci penandatanganan Single Sign-On

Untuk memperbarui kunci penandatanganan SSO domain, pertama-tama ambil kunci penandatanganan menggunakan operasi Mengambil kunci penandatanganan Single Sign-On, ubah, lalu kirim permintaan PUT ke URL feed kunci penandatanganan SSO. Pastikan nilai <id> ada dalam entri yang diperbarui sama persis dengan <id> entri yang ada. Untuk mengetahui informasi selengkapnya tentang kunci penandatanganan Single Sign-On berbasis SAML, lihat Membuat Kunci dan Sertifikat untuk Layanan Single Sign-On Google Workspace.

Saat memperbarui kunci penandatanganan Single Sign-On, kirim PUT HTTP ke URL feed kunci penandatanganan SSO:

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

XML permintaan PUT adalah:

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

Mengelola gateway dan perutean email

Bagian gateway email keluar menampilkan cara Admin Settings API mendukung pemilihan rute email keluar dari pengguna di domain Anda. Bagian pemilihan rute email menunjukkan cara mengarahkan pesan ke server email lain.

Mengambil setelan gateway email keluar

Untuk mengambil setelan gateway email keluar, kirim GET HTTP ke URL feed gateway, dan sertakan header Authorization seperti yang dijelaskan dalam Mengautentikasi ke layanan Setelan Admin:

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

Operasi ini tidak memiliki parameter dalam isi permintaan.

Respons yang berhasil akan menampilkan kode status HTTP 200 OK, beserta feed AtomPub dengan informasi status gateway email.

Respons GET menampilkan properti smartHost dan smtpMode. Untuk informasi selengkapnya tentang properti ini, lihat Memperbarui setelan gateway email keluar.

Contoh respons yang mungkin adalah:

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

Jika permintaan Anda gagal karena alasan tertentu, kode status yang berbeda akan ditampilkan. Untuk informasi selengkapnya tentang kode status Google Data API, lihat kode status HTTP.

Memperbarui setelan gateway email keluar

Untuk memperbarui setelan gateway email keluar domain, kirim permintaan HTTP PUT ke URL feed gateway:

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

XML permintaan PUT adalah:

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

Properti permintaan adalah:

smartHost
Alamat IP atau nama host server SMTP Anda. Google Workspace mengarahkan email keluar ke server ini.
smtpMode
Nilai defaultnya adalah SMTP. Nilai lainnya, SMTP_TLS, mengamankan koneksi dengan TLS saat mengirim pesan.

Respons yang berhasil akan menampilkan kode status HTTP 200 OK, beserta feed AtomPub dengan status setelan gateway email.

Jika permintaan Anda gagal karena alasan tertentu, kode status yang berbeda akan ditampilkan. Untuk informasi selengkapnya tentang kode status Google Data API, lihat kode status HTTP.

Mengelola setelan perutean email

Pertama, buat permintaan XML:

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

Properti permintaan adalah:

routeDestination
Tujuan ini adalah nama host atau alamat IP server email SMTP-In tempat email dirutekan. Nama host atau alamat IP harus diselesaikan untuk Google. Untuk mengetahui detail selengkapnya tentang menyelesaikan nama host email, lihat Uji coba Google Workspace dengan pemilihan rute email.
routeRewriteTo
Jika true (benar), kolom to: amplop SMTP pesan akan diubah menjadi nama host tujuan (nama host pengguna@tujuan), dan pesan akan dikirim ke alamat pengguna ini di server email tujuan. Jika false, email akan dikirim ke alamat email to: pesan asli (pengguna@nama host asli) di server email tujuan. Hal ini serupa dengan setelan 'Ubah amplop SMTP' konsol Admin. Untuk mengetahui informasi selengkapnya, lihat Setelan domain untuk pemilihan rute email.
routeEnabled
Jika true, fungsi pemilihan rute email akan diaktifkan. Jika false, fungsi tersebut akan dinonaktifkan.
bounceNotifications
Jika true, Google Workspace diaktifkan untuk mengirim notifikasi email tidak terkirim kepada pengirim saat pengiriman gagal.
accountHandling

Setelan ini menentukan pengaruh pemilihan rute email terhadap berbagai jenis pengguna di domain:

  • allAccounts -- Kirim semua email ke tujuan ini.
  • provisionedAccounts -- Mengirim email ke tujuan ini jika pengguna ada di Google Workspace.
  • unknownAccounts -- Mengirim email ke tujuan ini jika pengguna tidak ada di Google Workspace. Hal ini serupa dengan setelan 'Email pengiriman untuk' konsol Admin. Untuk informasi selengkapnya tentang prasyarat dan cara menggunakan perutean email, lihat Setelan domain untuk perutean email. ~ Untuk memublikasikan permintaan ini, kirim POST HTTP ke URL feed pemilihan rute email, dan sertakan header Authorization seperti yang dijelaskan dalam artikel Mengautentikasi ke layanan Setelan Admin:

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

Respons yang berhasil akan menampilkan kode status 200 OK HTTP, beserta feed AtomPub yang berisi informasi arsip.

Jika permintaan Anda gagal karena alasan tertentu, kode status yang berbeda akan ditampilkan. Untuk informasi selengkapnya tentang kode status Google Data API, lihat kode status HTTP.

Penghentian endpoint pada tanggal 31 Oktober 2018

Kami tidak lagi menggunakan endpoint berikut sebagai bagian dari pengumuman ini. Paket tersebut dihentikan pada tanggal 31 Oktober 2018 dan tidak lagi tersedia.

  • 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