English
Français
Tiếng ViệtAnonymous gửi vào
Trang tài liệu này đề cập đến tất cả các khía cạnh kỹ thuật của OBM-Sync. Nó hướng dẫn cho các lập trình viên cách kết nối đến một OBM-Sync cụ thể để quản lý lịch và danh bạ người dùng OBM.
# Biến, Quy ước
Các biến sau đây có thể được dùng trong tài liệu:
| Tên| Mô tả| Giá trị|
| ---- |
| OBM | Hostname hoặc địa chỉ IP của OBM Apache frontend. | my.obm.local |
| ROOT | Root URL cho server OBM-Sync của bạnr | /obm-sync/services/ |
| RC | Mã HTTP Response | 200, 400, etc. |
Trong tài liệu này, một chữ số trong mẫu `curl` cho trước cho phép bạn kiểm tra nhanh lời gọi của bất kỳ phương thức đã biết nào. Nếu do ngẫu nhiên trên máy bạn cài `xmllint` (hoặc bạn muốn cài `xmllint` thì tiện ích này nằm trong gói libxml2-utils của Linux) chúng tôi khuyên bạn nên thông đầu ra của `curl` qua lệnh sau nhằm định dạng đúng cho file XML kết quả:
xmllint --pretty 1 -
# Giao thức
OBM-Sync là một API cho phép thấy được thiết bị đầu cuối qua HTTP(S).
Để kết nối API, bạn phải gửi yêu cầu đến server, truyền số tham số. Server sẽ xử lý yêu cầu và gửi lại phản hồi.
Một thông tin phản hồi bao gồm:
* __Mã phản hồi__ HTTP , như trên bảng trên.
* Nội dung của thông báo phản hồi, nếu và chỉ nếu yêu cầu được xử lý (việc đó không có nghĩa yêu cầu đáp ứng _thành công_, nó chỉ có nghĩa rằng yêu cầu này đã được server xử lý). Nội dung bên trong của tin trả lời là một văn bản _XML_ phụ thuộc ngữ cảnh. Xem tài liệu bên dưới mô tả chi tiết hơn về XML.
### Yêu cầu
OBM-Sync chấp nhận cả yêu cầu _GET_ và_POST_ nhưng chúng tôi khuyên nên dùng _POST_.
OBM-Sync đã ựa chọn điểm cuối phụ thuộc URL. Tất cả URL phải theo định dạng:
### Endpoint hiện hành
Bảng dưới liệt kê các endpoint trong OBM-Sync. Các phương thức hiện có cho mỗi endpoint được liệt kê trong các chương cụ thể.
| ID | Tên| Mô tả|
| ----- |
| login | Endpoint quản lý phiên làm việc | Cho phép client đăng nhập hoặc đăng xuất khỏi OBM-Sync server. |
| calendar | Endpoint quản lý lịch làm việc |Cho phép client quản lý lịch người dùng. |
| book | Endpoint quản lý danh bạ | Cho phép client quản lý danh bạ người dùng. |
### Mã HTTP response
| Mã| Tên | Mô tả |
| ---- |
| 200 | OK | Gửi yêu cầu bất kỳ khi nào, được chấp nhận và xử lý, kể cả yêu cầu đó cuối cùng có chứa lỗi. |
| 4xx | _Variable_ | Gửi yêu cầu nhưng server không chấp nhận. Có một vài nguyên nhân nhưng thường do định dang URL kém. |
| 5xx | _Variable_ | Gửi yêu cầu khi có lỗi trong hệ thống trong quá trình xử lý . |
### Errors
Khi kết thúc một yêu cầu có error, server sẽ gửi một __error__ XML theo cấu trúc sau:
| Tag | Kiểu dữ liệu | Mô tả| Tần suất|
| ----- |
| message | String | Thông bao lỗi từ server. | 0 hoặc 1 |
| type | String | Kiểu error, nếu có khả năng sử dụng. | 0 hoặc 1 |
Cả __message__ và __type__ đều là lựa chọn tùy ý, nhưng trong một tài liệu _error_ ít nhất một trong hai.
Tài liệu mẫu _error_ dưới đây được gởi khi client cố truy cập vào tài nguyên được bảo vệ nhưng _id phiên_ không hợp lệ hoặc quá hạn:
#Endpoint quản lý phiên
Khách cần đăng nhập vào OBM-Sync trước khi gửi yêu cầu đến các endpoint.
Để đăng nhập hoặc đăng xuất cần dùng _Endpoint quản lý phiên_, được mô tả như dưới đây.
### doLogin
Phương thức xác thực trên OBM-Sync. Phương thức xác thực thực sự dựa trên việc cấu hình không nằm trong phạm vi tài liệu này.
_doLogin_ chấp nhận các tham số sau:
| Tên | Yêu cầu?|Mô tả| Giá trị mặc định|
| ----- |
| origin | có |Yêu cầu ban đầu. Có thể là bất kỳ chuỗi ký tự nào | N/A |
| login | có | Dùng để xác thực | N/A |
| password | có | Liên quan đến login | N/A |
#### Tài liệu XML trả về
Thực hiện thành công công việc trên _doLogin_ sẽ gửi về một __token__ XML , có cấu trúc dưới đây:
| Tag | Kiểu dữ liệu | Mô tả | Tần xuất|
| ----- |
| sid | String | Id phiên rất quan trọng và phải được gửi lại cho endpoint với tất cả các yêu cầu con. | 1 |
| version | None |Phiên bản OBM-Sync server: _major_, _minor_ và _release_| 1 |
| email | String | Địa chỉ email đầu tiên của người dùng. | 1 |
| domain | String | Tên miền domain của người dùng. _Uuid_ là id duy nhất của domain | 1 |
| settings | Danh sách tag _cài đặt_ |Danh sách các cài đặt của người dùng | 0 hoặc 1 |
| setting | String | Giá trị của các cài đặt. _name_ lấy tên của cài đặt đó. | 1+ |
| server-capabilities | Danh sách các tag của _server-capabilities_ | Danh sách tất cả server-capabilities | 0 hoặc 1 |
| server-capability | String | OBM-Sync sử dụng phương tiện truyền thông để quảng cáo cho một tính năng cụ thể. _name_ giữ tên của tính năng hỗ trợ. | 0+ |
Dưới đây là mẫu _token_ sau khi xác thực thành công:
##### Mẫu`curl`
curl -sk -XPOST -d"origin=mySuperSyncClient" -d"login=usera" -d"password=****" https://OBM/ROOT/login/doLogin
### doLogout
Cho phép khách _Logout_ khỏi OBM-Sync server. Chấp nhận các tham số sau:
| Tên | Yêu cầu? | Mô tả | Giá trị mặc định |
| ----- |
| sid | có | id _phiên làm việc_ cung cấp cho doLogin | N/A |
#### Tài liệu XML trả về
Phương thức này không trả về file XML. Mã phản hồi 200 của HTTP cho biết lời gọi thành công và phiên làm việc không hợp lệ.
#### Mẫu `curl`
curl -sk -XPOST -d"sid=6527b92a-2948-4c10-bdcf-fa8acb2d9693" https://OBM/ROOT/login/doLogout
# Endpoint quản lý danh bạ
Cho phép client tạo/sửa/xóa liên lạc trong danh bạ. Client cũng có thể nhận những thay đổi trên server về danh bạ.
### Cấu tạo chung của XML
#### Danh bạ
Là một thư mục trong XML. Thư mục trong XML như sau:
| Tag | Kiểu dữ liệu | Mô tả | Tần xuất |
| ----- |
| folder | Danh bạ | Thẻ gốc. Thuộc tính làm id cho danh bạ là `uid` | 1 |
| name | String | Tên danh bạ định nghĩa trong OBM. | 1 |
| ownerDisplayName | String | Tên hiện ra. Chỉ hiện ra khi danh bạ được chia sẻ| 0 hoặc 1 |
| ownerLoginAtDomain | String | _login@domain_ của chủ danh bạ. | 1 |
Một _folder_ XML trong _danh bạ liên lạc của _userb_:
#### Contact
Nó được biểu diễn bằng _contact_ trong XML, theo cấu trúc dưới đây:
| Tag | Kiểu dữ liệu | Mô tả | Tần suất |
| ----- |
| contact | Contact |Thẻ gốc. _collected_ cho biết contact này do người dùng tạo hay tự động lấy. | 1 |
| commonname | String | Tên hiện ra của contact. | 0 hoặc 1 |
| first | String | Tên contact.| 0 hoặc 1 |
| last | String | Họ contact. | 1 |
| middlename | String | Tên lót, tên giữa | 0 hoặc 1 |
| suffix | String | Suffix của contact, nếu có. | 0 hoặc 1 |
| service | String | Công việc của contact này trong công ty.| 0 hoặc 1 |
| title | String |Tên công việc. | 0 hoặc 1 |
| company | String | Tên công ty. | 0 hoặc 1 |
| aka | String | "Also Known As" , nickname . | 0 hoặc 1 |
| comment | String | Bất kỳ bình luận nào khi tạo ra contact này. | 0 hoặc 1 |
| manager | String |Tên người quản lý.| 0 hoặc 1 |
| assistant | String | Tên thư ký. | 0 hoặc 1 |
| addressbookid | Integer | Id duy nhất của dạnh bạ có contact này. | 1 |
| birthday | Integer | Ngày sinh.| 0 hoặc 1 |
| anniversary | Integer | Ngày thánh . | 0 hoặc 1 |
| caluri | String | Đường dẫn URL đến iCal lịch của contact. | 0 hoặc 1 |
| phones | Danh sách _phone_ tag | Danh sách tất cả số phone. | 0 hoặc 1 |
| phone | None |Nhãn là id cho số phone, các con số ghi số phone này ra. | 1+ |
| addresses | Danh sách _address_ tags | Danh sách tất cả các địa chỉ. | 0 hoặc 1 |
| address | String | Nhãn là id cho địa chỉ của các liên lạc, các thuộc tính khác mô tả chi tiết . | 1+ |
| websites| Danh sách _site_ tag | Danh sách tất cả các website . | 0 hoặc 1 |
| site | None | Nhãn làm id website và url là _URL_ của website. | 1+ |
| emails | Danh sách _mail_ tag |Danh sách tất cả email . | 0 hoặc 1 |
| mail | None | Nhãn là id cho địa chỉ email, các thuộc tính khác là địa chỉ email thật | 1+ |
| instantmessaging | Danh sách _im_ tags | Danh sách tất cả địa chỉ đang liên lạc. | 0 hoặc 1 |
| im | None | Nhãn là id cho địa chỉ email cụ thể, các thuộc tính khác là địa chỉ email thật và giao thức đang sử dụng | 1+ |
Trên những tag trên, thuộc tính nhãn (label) phải theo quy định dưới đây:
[
Trong đó:
* _Type_ là kiểu của địa chỉ email, cụ thể địa chỉ tin nhấn, số phone, vân vân. Giá trị chủ yếu của biến _Type_ variable là: WORK, VOICE, CALURI, INTERNET, ...
* _n_ đơn giản là một biến đếm và phải là duy nhất cho bất kỳ một _type_. Cụ thế, địa chỉ email đầu _n=1_, thứ hai _n=2_, và vân vân. Bởi vì chúng đều là địa chỉ email nên chúng có cùng _Type_ (_INTERNET_ trong trường hợp này).
Dưới đây là mẫu _contact_ trong XML:
### getAddressBookSync
Phương thức này cho phép client nhận những thay đổi về danh bạ (nó chấp nhận _in-sync_ với OBM backend) của người dùng đang đăng nhập. Nó hỗ trợ đồng bộ gia tăng.
Phương thức _getAddressBookSync_ trả về thông tin cho tất cả các danh bạ cho người đăng nhập được đăng ký, bao gồm cả những người chia sẻ. Phương thức này chấp nhận các tham số sau:
| Tên| Yêu cầu? | Mô tả| Giá trị mặc định |
| ----- |
| sid | Yes | A _id session_ trong phương thức _doLogin_. | N/A |
| lastSync | No | Thời điểm động bộ hóa thành công cuối cùng. Nếu được chỉ những thay đổi xuất hiện sau thời điểm này mới được gửi. | 0 |
#### Tài liệu XML trả về
Sau khi thực hiện thành công các thao tác trên, phương thức này sẽ gửi lại một __addressbook-changes__ . Cấu trúc của _addressbook-changes_ :
| Tag | Kiểu dữ liệu | Mô tả | Tần xuất |
| ----- |
| addressbook-changes | Những thay đổi danh bạ | _lastSync_ attribute là thời điểm đồng bộ. Thông thường client sẽ lưu lại và sau này gửi lại. | 1 |
| addressbooks | Danh sách những thay đổi danh bạ | Biểu diễn danh sách các danh bạ bị xóa/cập nhật/ bằng 1 hoặc 2 _folder_ tag. Xem thêm ở trên. | 0 hoặc 1 |
| contacts | Danh sách những thay đổi contacts | Biểu diễn danh sách các danh bạ bị xóa/cập nhật/ bằng 1 hoặc 2 _contact_ tag. Xem thêm ở trên. | 0 or 1 |
| removed | Danh sách những thành phần bị xóa| Danh sách những thành phần bị xóa. Được áp dụng cho danh bạ hoặc contact. | 1 |
| updated | Danh sách những thành phần được cập nhật | Danh sách những thành phần được cập nhật (bao gồm cái mới). Được áp dụng cho danh bạ hoặc contact. | 1 |
| folder | Danh bạ | Một danh bạ bị xóa hoặc được cập nhật mới. | 1+ |
| contact | Contact | Một contact bị xóa hoặc được cập nhật mới. | 1+ |
Mẫu _addressbook-changes_ :
####Mẫu `curl`
curl -sk -XPOST -d"lastSync=1370442470034" -d"sid=a736ad7f-b458-4863-b6b6-2ac2cc864bc1" https://OBM/ROOT/book/getAddressBookSync
### createContact
Cho phép client tạo một contact mới trong danh bạ. Danh sách tham số:
| Tên| Yêu cầu? | Mô tả| Giá trị mặc định |
| ----- |
| sid | có| Một _id session _trong _doLogin_ . | N/A |
| bookId | có| id duy nhất của danh bạ. | N/A |
| contact | có| XML của contact để tạo. Chi tiết xem bên trên. | N/A |
#### Tài liệu XML trả về
Thao tác trên thành công, phương thức trả về một __contact__ XML tạo mới contact.
#### Mẫu`curl`
curl -sk -XPOST -d"sid=df412e5d-e581-4420-9103-dca08df47d4b" -d"bookId=2" -d"contact=
### modifyContact
Cho phép client chỉnh sửa một contact trong danh bạ. Danh sách tham số:
| Tên | Yêu cầu? | Mô tả | Giá trị mặc định |
| ----- |
| sid | có | Một _id session _trong _doLogin_ . | N/A |
| bookId | có | id duy nhất của danh bạ. | N/A |
| contact | có | XML của contact. Xem phía trên. Xin nhớ rặng XML phải chứa _uid_ của contact. | N/A |
#### Tài liệu XML trả về
Thao tác trên thành công, phương thức trả về một __contact__ XML chỉnh sửa contact.
#### Mẫu `curl`
curl -sk -XPOST -d"sid=df412e5d-e581-4420-9103-dca08df47d4b" -d"bookId=2" -d"contact=
### removeContact
Cho phép client xóa một contact trong danh bạ. Danh sách tham số:
| Tên | Yêu cầu? | Mô tả | Giá trị mặc định |
| ----- |
| sid | có| Một _id session _trong _doLogin_ . | N/A |
| bookId | có| id duy nhất của danh bạ. | N/A |
| id | có| id của contact. | N/A |
#### Tài liệu XML trả về
Thao tác trên thành công, phương thức trả về một __contact__ XML contact đã bị xóa.
#### Mẫu `curl`
curl -sk -XPOST -d"sid=df412e5d-e581-4420-9103-dca08df47d4b" -d"bookId=2" -d"id=1262" https://OBM/ROOT/book/removeContact
### getContactFromId
Phương thức này cho phép client lấy thông tin chi tiết của contact khi chỉ biết id. Danh sách tham số:
| Tên | Yêu cầu? | Mô tả | Giá trị mặc định |
| ----- |
| sid | có| Một _id session _trong _doLogin_ . | N/A |
| book | có| Kiểu danh bạ. Tham số này có thể là _contacts_ hoặc _users_, phụ thuộc vào cái cần tìm. | None |
| id | có| id duy nhất của contact để lấy thông tin chi tiết. | N/A |
#### Tài liệu XML trả về
Thao tác trên thành công, phương thức trả về một __contact__ XML contact đã bị xóa.
#### Mẫu `curl`
curl -sk -XPOST -d"sid=df412e5d-e581-4420-9103-dca08df47d4b" -d"book=contacts" -d"id=1263" https://OBM/ROOT/book/getContactFromId
# Endpoint quản lý lịchNike Air Force