Özel kullanıcı alanlarını yönetme

Alana özel kullanıcı şemaları ekleyerek alanınızdaki kullanıcılar için özel alanlar tanımlayabilirsiniz. Bu alanları, kullanıcılarınızın üzerinde çalıştığı projeler, fiziksel konumları, işe giriş tarihleri veya işletme ihtiyaçlarınıza uygun diğer bilgiler gibi bilgileri depolamak için kullanabilirsiniz.

Başlamak için alanınızla ilgili özel alanları tanımlamak üzere bir veya daha fazla şema oluşturun. Alan adı, tür (dize, boole, tam sayı vb.), tek veya çok değerli olup olmadığı ve değerlerinin alanınızdaki herhangi bir kullanıcı tarafından mı yoksa yalnızca yöneticiler ve ilişkili kullanıcı tarafından mı görüntülenebileceği gibi bir dizi özellik belirtebilirsiniz.

Bir şema tanımlandıktan sonra özel alanlar, standart alanlar gibi davranır. Bu alanları alanınızdaki kullanıcıları güncellerken ayarlayabilir, users.get ve users.list ile getirebilir ve özel alanları arama yapabilirsiniz.

Kullanıcı profilinde özel alanlar ayarlama

Şemayı güncellemek veya oluşturmak için customSchemasözellik oluşturun ve kullanıcı kaynağına ekleyin. customSchemas özelliği içinde özel alanlar, standart JSON biçiminde şemaya göre gruplandırılır:

"customSchemas": {
  "schema1": {
    "field1": "value1",
    "field2": [
      { "value": "value2a" },
      { "value": "value2b" },
      ...
    ],
    ...
  },
  "schema2": {
    "field3": "value3",
    ...
  },
  ...
}

Tek değerli özel alanlar, "field1": "value1" gibi basit anahtar/değer çiftleri olarak ayarlanır. Çok değerli özel alanlar, API'deki addresses ve phones gibi standart çok değerli alanlar gibi nesne dizileri olarak ayarlanır. Bu değer nesneleri aşağıdaki anahtarları destekler:

Anahtarlar
value Depolanacak değer (zorunlu).
type Değerin türü (isteğe bağlı). Olası değerler:
  • custom
  • home
  • other
  • work
customType Değerin özel türü (isteğe bağlı). type, custom olarak ayarlandığında kullanılmalıdır.

Bir şemadaki özel alan güncelleme sırasında belirtilmezse değiştirilmez. Güncelleme sırasında customFields içinde bir şema belirtilmezse söz konusu şemadaki tüm özel alanlar değiştirilmeden bırakılır. Özel alanı veya özel şemayı profilden silmek için null olarak ayarlamanız gerekir:

"schema1": {
  "field1": null // deletes field1 from this profile.
}

JSON isteği

Aşağıdaki örnekteki çağrı, bir kullanıcıyı günceller ve employmentData özel şeması için değerler ayarlar:

PATCH https://admin.googleapis.com/admin/directory/v1/users/liz@example.com

{
  "customSchemas": {
    "employmentData": {
      "employeeNumber": "123456789",
      "jobFamily": "Engineering"
      "location": "Atlanta",
      "jobLevel": 8,
      "projects": [
        { "value": "GeneGnome" },
        { "value": "Panopticon", "type": "work" },
        { "value": "MegaGene", "type": "custom", "customType": "secret" }
      ]
    }
  }
}

Kullanıcı profilindeki özel alanları okuma

users.get veya users.list isteğinde projection parametresini custom veya full olarak ayarlayarak kullanıcı profilindeki özel alanları getirebilirsiniz.

Kullanıcı profilindeki özel alanlarda arama yapma

users.list isteğinde query parametresini kullanarak özel alanlarda arama yapabilirsiniz. Özel alanı schemaName.fieldName söz dizimiyle istersiniz. Örneğin:

employmentData.projects:"GeneGnome"

GeneGnome projesinde çalışan tüm personeli döndürür. Sorgu

employmentData.location="Atlanta" employmentData.jobLevel>=7

Atlanta'daki 7. iş seviyesinin üzerindeki tüm çalışanları döndürür. Daha fazla bilgi için Kullanıcıları arama başlıklı makaleyi inceleyin.

Özel kullanıcı şeması oluşturma

Özel kullanıcı şeması, Google Workspace hesabınızın tüm alanlarına eklenebilir. Alanlarınızda özel bir kullanıcı şeması oluşturmak için aşağıdaki POST isteğini kullanın ve İstekleri yetkilendirme bölümünde açıklanan yetkilendirmeyi ekleyin. İstek sorgusu dizesi özellikleri için API Referansı'na bakın.

POST https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas

Tüm oluşturma istekleri için isteği karşılamak üzere gereken bilgileri göndermeniz gerekir. İstemci kitaplıklarını kullanıyorsanız bu kitaplıklar, seçtiğiniz dildeki veri nesnelerini biçimlendirilmiş JSON veri nesnelerine dönüştürür.

JSON isteği

Aşağıdaki örnekte, özel şema oluşturma isteği gösterilmektedir. İstek ve yanıt özelliklerinin tam listesi için API Referansı'na bakın.

{
  "schemaName": "employmentData",
  "fields": [
    {
      "fieldName": "EmployeeNumber",
      "fieldType": "STRING",
      "multiValued": "false"
    },
    {
      "fieldName": "JobFamily",
      "fieldType": "STRING",
      "multiValued": "false"
    }
  ]
}

Başarılı bir yanıt, yeni özel şemanın özellikleriyle birlikte HTTP 201 durum kodu döndürür.

Özel şema sınırları

  • Bir hesapta en fazla 100 özel şemaya izin verilir.
  • Bir hesapta en fazla 100 özel alana izin verilir.
  • Tek değerli bir özel alan için string alanında izin verilen maksimum karakter sayısı 500'dür. Çok değerli özel alanlarda, izin verilen öğe sayısı atanan değerlerin boyutuna bağlıdır. Örneğin, her biri 100 karakterden oluşan 150 değer veya her biri 500 karakterden oluşan 50 değer ekleyebilirsiniz.
  • Özel şemalarda ve alan adlarında alfanümerik karakterlere, alt çizgilere (_) ve kısa çizgilere (-) izin verilir.
  • Alan türünün değiştirilmesine izin verilmez.
  • Tek değerli bir alan çok değerli hale getirilebilir ancak tersi işlem yapılamaz.
  • Özel şemalar veya alanlar yeniden adlandırılamaz.

Özel kullanıcı şemasını güncelleme

Özel bir şemayı güncellemek için aşağıdaki PUT isteğini kullanın ve İstekleri yetkilendirme bölümünde açıklanan yetkilendirmeyi ekleyin. schemaKey, şema adı veya benzersiz şema id olabilir. İstek ve yanıt özellikleri için API Referansı'na bakın.

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

JSON isteği

Aşağıdaki örnekte, şema employmentData ilk oluşturulduğunda JobFamily alanı içeriyordu. İstek, employmentData öğesini yalnızca bir EmployeeNumber alanı içerecek şekilde güncelliyor:

PUT https://admin.googleapis.com/admin/directory/v1/customer/my_customer/schemas/employmentData

{
  "kind": "admin#directory#schema",
  "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
  "etag": "\"St7vIdePbbDsQUvvrssynd-6JLg/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
  "schemaName": "employmentData",
  "fields": [
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
      "etag": "\"St7vIdePbbDsQUvvrssynd-6JLg/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
      "fieldType": "STRING",
      "fieldName": "EmployeeNumber",
      "multiValued": "false"
    }
  ]
}

Tüm güncelleme istekleri için isteği karşılamak üzere gereken bilgileri göndermeniz gerekir.

Başarılı bir yanıt, güncellenmiş şema kaynağıyla birlikte HTTP 200 durum kodu döndürür.

Özel kullanıcı şeması alma

Özel bir şemayı almak için aşağıdaki GET isteğini kullanın ve İstekleri yetkilendirme bölümünde açıklanan yetkilendirmeyi ekleyin. schemaKey, şema adı veya benzersiz şema id olabilir. İstek ve yanıt özellikleri için API Referansı'na bakın.

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas/schemaKey

Başarılı bir yanıt, özel şemanın özellikleriyle birlikte HTTP 200 durum kodu döndürür.

{
  "kind": "admin#directory#schema",
  "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
  "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
  "schemaName": "employmentData",
  "fields": [
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
      "fieldType": "STRING",
      "fieldName": "EmployeeNumber"
    },
    {
      "kind": "admin#directory#schema#fieldspec",
      "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
      "fieldType": "STRING",
      "fieldName": "JobFamily"
    }
  ]
}

Tüm özel kullanıcı şemalarını alma

Aynı hesaptaki tüm özel şemaları almak için aşağıdaki GET isteğini kullanın ve İstekleri yetkilendirme bölümünde açıklanan yetkilendirmeyi ekleyin.İstek ve yanıt özellikleri için API Referansı'na bakın.

GET https://admin.googleapis.com/admin/directory/v1/customer/my_customer or customerId/schemas

Başarılı bir yanıt, hesapla ilgili özel şemalarla birlikte HTTP 200 durum kodu döndürür.

{
  "kind": "admin#directory#schemas",
  "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/iJ1eWn5AKuR-xTdwH_2IBlvSSKo\"",
  "schemas": [
    {
      "kind": "admin#directory#schema",
      "schemaId": "dKaYmUwmSZy5lreXyh75hQ==",
      "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/PKg63GvWb7bnVSNRomd_O-Vi66w\"",
      "schemaName": "employmentData",
      "fields": [
        {
          "kind": "admin#directory#schema#fieldspec",
          "fieldId": "21_B4iQIRY-dIFGFgAX-Og==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/LZxiGaz6_N4R40OpKbDhOcy2qiE\"",
          "fieldType": "STRING",
          "fieldName": "EmployeeNumber"
        },
        {
          "kind": "admin#directory#schema#fieldspec",
          "fieldId": "ZKy0QtoMRy2QlM-4sAsPtQ==",
          "etag": "\"KYnPjBPqr8knK6v7rpxly9BhNeY/jEULI-ZiqywQIHXgc8evEcTE4Cc\"",
          "fieldType": "STRING",
          "fieldName": "JobFamily"
        }
      ]
    }
  ]
}