15.11 ADSI. Интерфейс IADs

Интерфейс IADs в ADSI, свойства и методы любого объекта Active Directory, свойства ADsPath, Class, GUID, Name, Parent, Schema, методы GetInfo(), SetInfo(), Get(), GetEx(), GetInfoEx(), Put(), PutEx()

Интерфейс IADs определяет набор базовых свойств и методов для любого объекта ADSI. Помимо стандартных методов, унаследованных от интерфейсов IUnknown и IDispatch, этот интерфейс определят набор своих собственных свойств и методов:

• ADsPath — это свойство возвращает отличительное имя объекта в Active Directory. Значение этого свойства может выглядеть по разному в зависимости от того, как именно вы получили ссылку на данный объект. Если использовались обычные пути LDAP (с традиционным отличительным именем), то это свойство возвращает значение вида

LDAP://LONDON3/cn=TestUser1,CN=Users,dc=nwtraders1,dc=msft

или

LDAP://cn=TestUser1,cn=Users,dc=nwtraders1,dc=msft

а если вы получаете ссылку на объект при помощи GUID, то это свойство возвращает значение с GUID, например:

LDAP://LONDON3/<GUID=c0f59dfcf507d311a99e0000f879f7c7>

• Class — это свойство возвращает имя класса Active Directory, к которому принадлежит данный объект, согласно схеме Active Directory. Например, для домена Active Directory значение будет выглядеть как  "domainDNS", а для объекта пользователя — просто "user".
• GUID — это свойство возвращает глобально-уникальный идентификатор объекта Active Directory. При обращении к данному свойству его значение автоматически преобразуется в строковый формат из формата octet string, в котором GUID хранится на контроллере домена.
• Name — это имя возвращает относительное отличительное имя данного объекта (relative distinguished name, RDN), то есть имя без указания пути к объекту в каталоге Active Directory. Это имя может выглядеть, например, как "cn=TestUser1".
• Parent — это свойство возвращает значение свойства ADsPath для родительского контейнера данного объекта. Например, если объект пользователя находится в контейнере Users, то это свойство для данного объекта пользователя вернет значение вида "LDAP://cn=Users,dc=nwtraders1,dc=msft".
• Schema — это свойство возвращает значение свойства ADsPath для родительского контейнера данного объекта. Например, для объекта пользователя это свойство вернет значение "LDAP://schema/user".
• GetInfo() — этот метод позволяет заново скачать в оперативную память компьютера, на котором создан объект ADSI, информацию о значениях свойств этого объекта с контроллера домена. Другое назначение этой операции — обновление кэша свойств.
• SetInfo() — важнейший метод, который записывает информацию об изменениях, произведенных с объектом ADSI в оперативной памяти, на контроллер домена, делая таким образом изменения постоянными. Фактически любая операция по внесению изменений в Active Directory средствами ADSI завершается вызовом метода SetInfo(). Контроллер домена по разным причинам может отказаться сохранять внесенные изменения (например, настроенный для пользователя пароль не соответствует парольной политике домена), поэтому лучше всего для вызова этого метода настраивать обработчик ошибок.
• Get() — этот метод, как и метод GetInfo(), обновляет кэш свойств, скачивая значения заново с контроллера домена. Однако GetInfo() обновляет значения всех свойств, а Get() — только указанного вами. Имя этого свойства передается методу Get() в качестве параметра.
• GetEx() — этот метод делает практически то же, что и метод Get(): обновляет значение в кэше в оперативной памяти для указанного свойства. Однако этот метод возвращает немного отличающиеся значения. Если для какого-то свойства предусмотрено единственное значение (например, строковое), метод Get() вернет просто это строковое значение. Если для этого свойства предусмотрено несколько строковых значений,  то метод Get() вернет массив строковых значений. Метод GetEx() всегда возвращает массив значений типа Variant, вне зависимости от того, было ли для свойства настроено одно значение или несколько. Поэтому метод GetEx() очень удобно использовать в ситуации, когда неизвестно, вернется одно значение или несколько. Пример применения GetEx() в такой ситуации может выглядеть так:

Dim x

otherNumbers = x.GetEx("otherHomePhone")

For Each homeNum In otherNumbers

Wscript.Echo   homeNum

Next

При использовании метода Get() потребуется более сложный код с проверкой типа возвращаемого значения:

Dim x

otherNumbers = x.Get("otherHomePhone")

If VarType(otherNumbers) = vbString Then

Wscript.Echo otherNumbers

Else

  For Each homeNum In otherNumbers

    Wscript.Echo homeNum

  Next

End If

• GetInfoEx() — этот метод, как и метод GetEx(), заново скачивает значения с контроллера домена для указанного вами свойства. Отличием этого метода является то, что метод GetEx() принимает в качестве параметра имя единственного свойства, а метод GetInfoEx() — массив с именами свойств. Соответственно, этот метод может обновить значения не для одного свойства, а для набора свойств. Пример вызова этого метода может выглядеть так:

Dim x

On Error GoTo Cleanup

Set x = GetObject("LDAP://CN=JeffSmith,CN=Users,DC=Fabrikam,DC=com")

' Скачиваем в кэш значения атрибутов givenName и sn

x.GetInfoEx Array("givenName", "sn"), 0

Wscript.Echo x.Get("givenName") 

Wscript.Echo x.Get("sn")

' Поскольку атрибута homePhone в кэше нет, метод GetInfo() будет вызван автоматически

Wscript.Echo x.Get("homePhone")

Cleanup:

   If(Err.Number<>0) Then

      MsgBox("An error has occurred. " & Err.Number);

   End If

   Set x = Nothing

• Put() — этот метод позволяет присвоить значение свойству в кэше свойств для объекта ADSI в оперативной памяти. Чаще всего он используется в ситуации, когда объект ADSI создан только в оперативной памяти и не сохранен на контроллере домена. В этом случае прямое присвоение значения свойству вернет ошибку (поскольку свойства реально у объекта еще нет, как нет пока и самого объекта в Active Directory). Метод Put() позволяет положить информацию о значении свойства в кэш в оперативной памяти, чтобы потом при вызове метода SetInfo() настроенные значения свойств были сохранены вместе с объектом в базе данных Active Directory. Обычно метод Put() используется только для присвоения значений обязательным свойствам, без которых сохранение объекта невозможно. Далее вызывается метод SetInfo(), и работа со значениями свойств идет уже обычным порядком:

Set oOU = GetObject ("LDAP://OU=HQ, DC=nwtraders, DC=msft")

Set oUSR = oOU.Create("user", "CN=Kathie Flood1")

oUSR.Put "samAccountName", "kathief1"

OUSR.Put "userPrincipalName", "Kathie@nwtraders.msft"

oUSR.SetInfo

OUSR.SetPassword "TempPassword"

oUSR.AccountDisabled = False

oUSR.SetInfo

Этот метод принимает два параметра: первый — имя свойства, а второй — значение для этого свойства.

• PutEx() — этот метод предназначен для тех же целей, что и метод Put(), но возможностей в нем предусмотрено больше. В качестве еще одного параметра этот метод принимает информацию о том, что именно нужно сделать с указанными вами значением свойства. В вашем распоряжении — следующие варианты (значения перечисления ADS_PROPERTY_OPERATION_ENUM):
• ADS_PROPERTY_CLEAR (1) — очистить данное свойство, убрав все его значения;
• ADS_PROPERTY_UPDATE (2) — обновить значение для данного свойства, заменив его указанным вами новым значением;
• ADS_PROPERTY_APPEND (3) — новое значение должно добавиться к уже существующим (если свойство поддерживает набор значений, например, для телефонных номеров);
• ADS_PROPERTY_DELETE (4) — указанное вами значение должно быть удалено из набора значений для данного свойства.

Пример применения метода PutEx() может выглядеть следующим образом:

Dim x

On Error GoTo Cleanup

Set x = GetObject("LDAP://CN=JeffSmith,CN=Users,DC=Fabrikam,DC=com")

' Предположим, что у атрибута otherHomePhone есть два значения:

' 425-707-9790, 425-707-9791

' Добавляем еще одно значение

x.PutEx ADS_PROPERTY_APPEND, "otherhomePhone", Array("425-707-9792") 

x.SetInfo             

' Теперь значений 3: 425-707-9790,425-707-9791,425-707-9792.

' Удаляем два значения

x.PutEx ADS_PROPERTY_DELETE, "otherHomePhone", Array("425-707-9790", "425-707-9791")

x.SetInfo             

' Изменяем оставшееся значение

x.PutEx ADS_PROPERTY_UPDATE, "otherHomePhone", Array("425-707-9793", "425-707-9794")

x.SetInfo             

' И удаляем его

x.PutEx ADS_PROPERTY_CLEAR, "otherHomePhone",  vbNullString

x.SetInfo             

' Значений у атрибута больше нет

Cleanup:

    If(Err.Number<>0) Then

        MsgBox("An error has occurred. " & Err.Number)

    End If

    Set x = Nothing

Получить учебные материалы по этому курсу