Ringkasan Admin Settings API

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

Setelan domain ini mencakup 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 sesuai dengan 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 bagi developer yang ingin menulis aplikasi klien yang dapat mengubah dan mengambil informasi tentang domain Google Workspace. Contoh ini memberikan contoh interaksi dasar Admin Settings API menggunakan XML mentah dan HTTP.

Dokumen ini mengasumsikan bahwa Anda memahami ide-ide umum di balik protokol Google Data API, dan sudah terbiasa dengan konsol Admin Google Workspace. Untuk mengetahui 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 menggunakan Admin Settings API dan gunakan Email Settings API untuk mengonfigurasi setelan email pengguna.

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, 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 melibatkan proses memasukkan informasi yang diperlukan agar layanan Google Workspace dapat berkomunikasi dengan penyedia identitas yang menyimpan informasi login pengguna, serta menyiapkan link yang akan dituju pengguna untuk login, logout, dan untuk 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 terkait 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:

• Membuat kunci -- Dengan penyedia identitas Anda, buat serangkaian kunci publik dan pribadi menggunakan algoritma DSA atau RSA. Kunci publik berada 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 pada Admin Settings API untuk mendaftarkan public key certificate Anda dengan Google.
• Menyiapkan setelan SSO -- Gunakan setelan Single Sign-On pada Admin Settings API untuk mengonfigurasi setelan yang digunakan untuk komunikasi 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 pemilihan rute dan gateway

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 mengetahui 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 mentah dan HTTP. Contoh bahasa default domain ini menunjukkan sintaksis XML dan HTTP lengkap untuk isi entri permintaan dan respons yang umum di 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

Bahasa default domain PUT permintaan AtomPub entry XML 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 pasangan nilai kunci tunggal yang berisi informasi tentang properti yang ingin Anda ambil atau perbarui. Ini bersifat umum untuk 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 cukup dengan 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 di bagian 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.

ScriptLogoutUri

Alamat tujuan pengiriman pengguna saat mereka logout dari aplikasi web.

changePasswordUri

Alamat tujuan pengiriman pengguna saat mereka ingin mengubah sandi SSO untuk aplikasi web.

aktifkanSSO

Mengaktifkan SSO berbasis SAML untuk domain ini. Jika sebelumnya Anda telah mengonfigurasi setelan SSO, dan kemudian Anda menetapkan enableSSO ke enableSSO=false, setelan yang sebelumnya telah Anda masukkan akan tetap disimpan.

Daftar Putih

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

useDomainSpecificPenerbit

Penerbit khusus domain dapat digunakan dalam permintaan SAML ke penyedia identitas. Meskipun tidak diperlukan untuk sebagian besar deployment SSO, fitur ini berguna pada 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 Penerbit di 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, pertama-tama ambil setelan SSO menggunakan operasi Pengambilan setelan Single Sign-On, ubah setelan, 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 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 mengetahui 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 di 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 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, 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 HTTP PUT 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.

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 HTTP GET ke URL feed gateway, dan sertakan header Authorization seperti yang dijelaskan di bagian 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.

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 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 HTTP PUT 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 mengarahkan email keluar ke server ini.

Mode smtp

Nilai defaultnya adalah SMTP. Nilai lainnya, SMTP_TLS, mengamankan koneksi dengan TLS saat mengirim pesan.

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

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

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

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

ruteDestination

Tujuan ini adalah nama host atau alamat IP server email SMTP-In tempat email diarahkan. Nama host atau alamat IP harus di-resolve untuk Google. Untuk mengetahui detail selengkapnya tentang cara menetapkan nama host email, lihat Menguji coba Google Workspace dengan pemilihan rute email.

routeRewriteTo

Jika benar, kolom to: amplop SMTP pesan akan diubah menjadi nama host tujuan (nama host pengguna@tujuan), dan pesan akan dikirimkan ke alamat pengguna tersebut 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, fungsinya akan dinonaktifkan.

pantulan notifikasi

Jika true, Google Workspace akan diaktifkan untuk mengirim notifikasi email tidak terkirim kepada pengirim saat pengiriman gagal.

Penanganan akun

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

• allAccounts -- Mengirim 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. Hal ini serupa dengan setelan 'Email pengiriman untuk' di 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 HTTP 200 OK, beserta feed AtomPub yang berisi 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 tidak lagi menggunakan endpoint berikut sebagai bagian dari pengumuman ini. Paket tersebut akan dihentikan mulai 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