Ringkasan Admin Settings API

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

Setelan domain ini mencakup banyak fitur yang tersedia di konsol Admin Google Workspace. Contoh penggunaan API ini mencakup pembuatan panel kontrol kustom atau integrasi domain Google Workspace ke dalam lingkungan lama yang ada.

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

Audiens

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

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, Anda sudah siap.

Catatan: Konfigurasikan setelan domain Anda menggunakan Admin Settings API dan gunakan Email Settings API untuk mengonfigurasi setelan email pengguna.

Tentang jenis feed Admin Settings API

Dengan Admin Settings API, Anda dapat 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. Khusus 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 informasi mendetail, lihat Memahami SSO berbasis SAML untuk Google Workspace.

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

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

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

Catatan: Untuk protokol yang tidak menggunakan alur login berbasis web, seperti beberapa program email POP/IMAP, pengguna login langsung dengan nama pengguna dan sandi Google Workspace mereka.

Setelan gateway dan pemilihan rute

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

Operasi pemilihan rute email memungkinkan administrator menentukan setelan pemilihan rute email tingkat domain. Hal ini mirip dengan fungsi pemilihan rute email di setelan Gmail konsol Admin. Untuk informasi selengkapnya, lihat Pemilihan rute email dan konfigurasi pengiriman ganda 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 dan HTTP mentah. 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 PUT HTTP ke URL feed gateway:

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

XML entry AtomPub permintaan bahasa default domain 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>

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 dengan hanya perlu memasukkan login dan sandi satu kali. Sandi ini disimpan oleh penyedia identitas domain, bukan oleh Google Workspace. Untuk 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 Melakukan autentikasi ke layanan Setelan Admin. Selain itu, 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 200 OK HTTP, 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>

Propertinya meliputi:

samlSignonUri

URL penyedia identitas tempat Google Workspace mengirim permintaan SAML untuk autentikasi pengguna.

samlLogoutUri

Alamat tempat pengguna akan diarahkan saat 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 telah mengonfigurasi setelan SSO sebelumnya, dan kemudian menetapkan enableSSO ke enableSSO=false, setelan yang telah Anda masukkan sebelumnya masih disimpan.

ssoWhitelist

ssoWhitelist adalah alamat IP network mask dalam format Classless Inter-Domain Routing (CIDR). ssoWhitelist menentukan pengguna yang login menggunakan SSO dan pengguna 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 mask jaringan.

useDomainSpecificIssuer

Penerbit khusus domain dapat digunakan dalam permintaan SAML ke penyedia identitas. Meskipun tidak diperlukan untuk sebagian besar deployment 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 mana yang akan dikaitkan dengan permintaan. Untuk informasi selengkapnya, lihat Bagaimana cara kerja elemen Issuer dalam permintaan SAML?

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

Memperbarui setelan Single Sign-On

Untuk memperbarui setelan SSO domain, ambil setelan SSO terlebih dahulu menggunakan operasi Mengambil setelan Single Sign-On, ubah, lalu kirim permintaan PUT ke URL feed SSO. Pastikan nilai <id> dalam entri yang diperbarui sama persis dengan <id> entri yang ada. Sertakan header Authorization seperti yang dijelaskan dalam Mengautentikasi ke layanan Admin Settings API. Selain itu, 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 200 OK HTTP, 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 mengetahui informasi selengkapnya tentang kode status Google Data API, lihat Kode status HTTP.

Perubahan pada setelan Single Sign-On tidak diizinkan jika pelanggan target telah mengaktifkan Persetujuan banyak pihak untuk tindakan sensitif. Permintaan akan gagal dengan errorCode="1811" dan reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

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. Selain itu, 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 mengetahui informasi selengkapnya tentang kode status Google Data API, lihat Kode status HTTP.

Memperbarui kunci penandatanganan Single Sign-On

Untuk memperbarui kunci penandatanganan SSO domain, ambil kunci penandatanganan terlebih dahulu menggunakan operasi Mengambil kunci penandatanganan Single Sign-On, ubah, lalu kirim permintaan PUT ke URL feed kunci penandatanganan SSO. Pastikan nilai <id> dalam entri yang diperbarui sama persis dengan <id> entri yang ada. Untuk 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>

Catatan: Properti signingKey diperlukan untuk permintaan ini.

Perubahan pada setelan Single Sign-On tidak diizinkan jika pelanggan target telah mengaktifkan Persetujuan banyak pihak untuk tindakan sensitif. Permintaan akan gagal dengan errorCode="1811" dan reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".

Mengelola gateway dan pemilihan rute email

Bagian gateway email keluar menunjukkan cara Admin Settings API mendukung pemilihan rute email keluar dari pengguna di domain Anda. Bagian pemilihan rute email menunjukkan cara merutekan 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 Melakukan autentikasi 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.

Catatan: Anda harus memiliki edisi Google Workspace yang memenuhi syarat untuk menggunakan fitur gateway keluar Google Workspace.

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 mengetahui informasi selengkapnya tentang properti ini, lihat Memperbarui setelan gateway email keluar.

Contoh kemungkinan respons 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 mengetahui 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 PUT HTTP ke URL feed gateway:

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

Catatan: Anda harus memiliki edisi Google Workspace yang memenuhi syarat untuk menggunakan fitur gateway keluar Google Workspace.

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 merutekan email keluar ke server ini.

smtpMode

Nilai defaultnya adalah SMTP. Nilai lain, SMTP_TLS, mengamankan koneksi dengan TLS saat mengirimkan pesan.

Catatan: Ikuti petunjuk agen transfer email Anda untuk mengonfigurasi email yang diteruskan yang dikirim dari Google Workspace.

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

Catatan: Kirim email dari Google Workspace ke pengguna di luar domain Anda untuk memverifikasi bahwa email keluar yang dikirim melalui gateway Anda berfungsi setelah perubahan Anda.

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

Mengelola setelan pemilihan rute 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 di-resolve untuk Google. Untuk mengetahui detail selengkapnya tentang me-resolve nama host email, lihat Menguji Google Workspace dengan pemilihan rute email.

routeRewriteTo

Jika benar, kolom to: amplop SMTP pesan akan diubah menjadi nama host tujuan (nama host user@destination), dan pesan akan dikirim ke alamat pengguna ini di server email tujuan. Jika false, email akan dikirim ke alamat email to: pesan asli (user@nama host asli) di server email tujuan. Ini mirip dengan setelan 'Ubah amplop SMTP' di konsol Admin. Untuk mengetahui informasi selengkapnya, lihat Setelan domain untuk pemilihan rute email.

routeEnabled

Jika true, fungsi pemilihan rute email diaktifkan. Jika false, fungsinya dinonaktifkan.

bounceNotifications

Jika true, Google Workspace akan diaktifkan untuk mengirim notifikasi pesan kembali 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 -- Kirim email ke tujuan ini jika pengguna ada di Google Workspace.
• unknownAccounts -- Kirim email ke tujuan ini jika pengguna tidak ada di Google Workspace. Ini mirip dengan setelan 'Email pengiriman untuk' di konsol Admin. Untuk mengetahui informasi selengkapnya tentang prasyarat dan cara menggunakan pemilihan rute email, lihat Setelan domain untuk pemilihan rute email. ~ Untuk memublikasikan permintaan ini, kirim POST HTTP ke URL feed pemilihan rute email, dan sertakan header Authorization seperti yang dijelaskan dalam Mengautentikasi ke layanan Setelan Admin:

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

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

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

Penghentian endpoint pada 31 Oktober 2018

Kami menghentikan penggunaan endpoint berikut sebagai bagian dari pengumuman ini. Fitur ini dihentikan pada 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