Halaman ini diterjemahkan oleh Cloud Translation API.

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 termasuk membuat panel kontrol kustom atau mengintegrasikan domain Google Workspace ke lingkungan lama yang 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 untuk developer yang ingin menulis aplikasi klien yang dapat mengubah dan mengambil informasi tentang domain Google Workspace. Panduan 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 tidak asing 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. 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 dihosting di 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 cara memasukkan informasi yang diperlukan bagi layanan Google Workspace untuk berkomunikasi dengan penyedia identitas yang menyimpan informasi login pengguna Anda, serta menyiapkan link yang akan menjadi tujuan pengiriman pengguna untuk login, logout, dan untuk mengubah sandi mereka. 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 dan bahwa respons SAML kunci pribadi tidak diubah selama transmisi jaringan.

Untuk ringkasan singkat API khusus tentang penggunaan setelan SSO, dapatkan sertifikat kunci publik 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 Anda -- Dengan penyedia identitas Anda, buat serangkaian kunci publik dan pribadi menggunakan algoritme DSA atau RSA. Kunci publik menggunakan 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.
Daftar dengan Google -- Gunakan setelan Single Sign-On Admin Settings API untuk mendaftarkan sertifikat kunci publik Anda ke 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.

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. Fungsi ini mirip dengan fungsi pemilihan rute email pada 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 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

Bahasa default domain PUT 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. Permintaan ini umum untuk semua isi permintaan Admin Settings API.

Elemen entry respons bahasa default domain menampilkan properti smartHost dan smtpMode bersama dengan 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 perlu memasukkan login dan sandi satu kali. Sandi ini disimpan oleh penyedia identitas domain, bukan 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 mencakup:

SignonUri saml: URL penyedia identitas tempat Google Workspace mengirimkan permintaan SAML untuk autentikasi pengguna.
samlLogoutUri: Alamat yang akan dituju pengguna saat mereka logout dari aplikasi web.
gantiPasswordUri: Alamat yang dituju 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 menetapkan enableSSO ke enableSSO=false, setelan yang sebelumnya dimasukkan masih akan disimpan.
ssoDaftar putih: ssoList adalah alamat IP mask jaringan dalam format Classless Inter-Domain Pemilihan Rute (CIDR). UIsso 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 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 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 lain akan ditampilkan. Untuk mendapatkan informasi lebih lanjut 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> dari 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 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 beberapa alasan, kode status lain akan ditampilkan. Untuk mendapatkan informasi lebih lanjut 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 200 OK HTTP, 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 lain akan ditampilkan. Untuk mendapatkan informasi lebih lanjut 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 Kunci penandatanganan Single Sign-On, ubah kunci tersebut, lalu kirim permintaan PUT ke URL feed kunci penandatanganan SSO. Pastikan nilai <id> dalam entri yang diperbarui sama persis dengan <id> dari 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>

Mengelola pemilihan rute dan gateway email

Bagian gateway email keluar menunjukkan cara Admin Settings API mendukung pemilihan rute email keluar dari pengguna di domain Anda. Bagian pemilihan rute email menampilkan 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 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 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 beberapa alasan, kode status lain akan ditampilkan. Untuk mendapatkan informasi lebih lanjut 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

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 200 OK HTTP, beserta feed AtomPub dengan status setelan gateway email.

Jika permintaan Anda gagal karena beberapa alasan, kode status lain akan ditampilkan. Untuk mendapatkan informasi lebih lanjut 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 menyelesaikan 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 dikirim ke alamat pengguna ini di server email tujuan. Jika false, email dikirim ke alamat email to: pesan asli (pengguna@nama host asli) di server email tujuan. Setelan ini mirip dengan setelan 'Ubah amplop SMTP' konsol Admin. Untuk mengetahui informasi selengkapnya, lihat Setelan domain untuk pemilihan rute email.

routeEnabled

Jika true, fungsionalitas pemilihan rute email akan diaktifkan. Jika false, fungsinya dinonaktifkan.

pantulanNotifikasi

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

Penanganan akun

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

allAccounts -- Mengirim semua email ke tujuan ini.
provisionedAccounts -- Mengirim email ke tujuan ini jika pengguna menggunakan Google Workspace.
unknownAccounts -- Mengirim email ke tujuan ini jika pengguna tidak ada di Google Workspace. Setelan ini mirip dengan setelan 'Email pengiriman untuk' pada 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 200 OK HTTP, beserta feed AtomPub dengan informasi arsip.

Jika permintaan Anda gagal karena beberapa alasan, kode status lain akan ditampilkan. Untuk mendapatkan informasi lebih lanjut 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. Keduanya berhenti digunakan 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