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 antara lain 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. Fungsi 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 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.

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

Tentang jenis feed API Setelan Admin

API Setelan Admin memungkinkan Anda mengelola kategori setelan domain ini:

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. 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 informasi selengkapnya, lihat Memahami SSO berbasis SAML untuk Google Workspace.

Untuk mengonfigurasi SSO, Anda harus memasukkan informasi yang diperlukan agar layanan Google Workspace dapat berkomunikasi dengan penyedia identitas yang menyimpan data pengguna Anda. informasi login, 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 dihasilkan 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 public key certificate dari penyedia identitas Anda, daftarkan kunci publik dengan Google, dan siapkan setelan kueri SSO berbasis SAML. Untuk pesan error, lihat Memecahkan Masalah SSO:

• Membuat kunci -- Dengan Penyedia Identitas Anda, buat kumpulan 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 API Setelan Admin untuk mendaftarkan sertifikat kunci publik Anda ke Google.
• Menyiapkan setelan SSO -- Gunakan setelan Single Sign-On API Setelan Admin 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 menggunakan 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 perutean email memungkinkan administrator menentukan setelan perutean email tingkat domain. Hal ini serupa dengan fungsi perutean email di setelan Gmail konsol Admin. Untuk informasi selengkapnya, lihat Pemilihan rute email dan konfigurasi pengiriman ganda pada 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 PUT HTTP ke URL feed gateway:

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

Bahasa default domain PUT yang meminta 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 satu pasangan nilai kunci yang berisi informasi tentang properti yang ingin Anda ambil atau perbarui. Hal ini umum untuk semua badan 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 sekali. 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 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 mencakup:

samlSignonUri

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

samlLogoutUri

Alamat yang akan dituju pengguna saat mereka logout dari aplikasi web.

changePasswordUri

Alamat yang menjadi tujuan pengalihan pengguna saat mereka ingin mengubah sandi SSO untuk aplikasi web.

enableSSO

Mengaktifkan SSO berbasis SAML untuk domain ini. Jika sebelumnya Anda telah mengonfigurasi setelan SSO, lalu menetapkan enableSSO ke enableSSO=false, setelan yang sebelumnya dimasukkan masih disimpan.

ssoWhitelist

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 masuk menggunakan SSO. Untuk 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 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 yang akan dikaitkan dengan permintaan. Untuk informasi selengkapnya, lihat Bagaimana cara kerja elemen Penerbit dalam permintaan SAML?

Jika permintaan Anda gagal karena beberapa alasan, 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 Mengambil setelan Single Sign-On, mengubahnya, lalu mengirim 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 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 beberapa alasan, 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. 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 beberapa alasan, 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 mengupdate 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> 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>

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 perutean 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 mengarahkan pesan ke server email lain.

Mengambil setelan gateway email keluar

Untuk mengambil setelan gateway email keluar, kirim GET HTTP ke URL feed gateway, lalu 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.

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

Respons yang berhasil akan mengembalikan 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 beberapa alasan, 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 akan mengarahkan email keluar ke server ini.

smtpMode

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

Catatan: Ikuti petunjuk agen transfer email Anda untuk mengonfigurasi email yang direlai 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 perubahan dilakukan.

Jika permintaan Anda gagal karena beberapa alasan, 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:

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 cara me-resolve nama host email, lihat Uji coba Google Workspace dengan pemilihan rute email.

routeRewriteTo

Jika true (benar), kolom to: amplop SMTP pesan 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: milik pesan asli (pengguna@nama host asli) di server email tujuan. Hal ini serupa dengan 'Ubah amplop SMTP' konsol Admin deskripsi tempat. Untuk mengetahui informasi selengkapnya, lihat Setelan domain untuk pemilihan rute email.

routeEnabled

Jika true, fungsi pemilihan rute email diaktifkan. Jika false, fungsinya 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 bagi 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 'Pengiriman email untuk' konsol Admin deskripsi tempat. 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 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 beberapa alasan, kode status yang berbeda akan ditampilkan. Untuk mengetahui informasi selengkapnya tentang kode status Google Data API, lihat kode status HTTP.

Endpoint dihentikan pada 31 Oktober 2018

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