`xmlrpc.server` --- Máy chủ XML-RPC cơ bản¶

Source code: Lib/xmlrpc/server.py

Mô-đun xmlrpc.server cung cấp khung máy chủ cơ bản cho các máy chủ XML-RPC được viết bằng Python. Máy chủ có thể ở trạng thái tự do, sử dụng SimpleXMLRPCServer hoặc được nhúng trong môi trường CGI, sử dụng CGIXMLRPCRequestHandler.

Cảnh báo

Mô-đun xmlrpc.server không an toàn trước dữ liệu được xây dựng độc hại. Nếu bạn cần phân tích dữ liệu không đáng tin cậy hoặc chưa được xác thực, hãy xem bảo mật XML.

sẵn có: not WASI.

Mô-đun này không hoạt động hoặc không có trên WebAssembly. Xem Nền tảng WebAssugging để biết thêm thông tin.

class xmlrpc.server.SimpleXMLRPCServer(addr, requestHandler=SimpleXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=False)¶: Tạo một phiên bản máy chủ mới. Lớp này cung cấp các phương thức đăng ký các hàm có thể được gọi bằng giao thức XML-RPC. Tham số requestHandler phải là tham số gốc cho các phiên bản xử lý yêu cầu; nó mặc định là SimpleXMLRPCRequestHandler. Các tham số addr và requestHandler được truyền tới hàm tạo socketserver.TCPServer. Nếu logRequests là đúng (mặc định), các yêu cầu sẽ được ghi lại; đặt tham số này thành false sẽ tắt ghi nhật ký. Các tham số allow_none và encoding được chuyển đến xmlrpc.client và kiểm soát các phản hồi XML-RPC sẽ được máy chủ trả về. Tham số bind_and_activate kiểm soát xem server_bind() và server_activate() có được hàm tạo gọi ngay lập tức hay không; nó mặc định là đúng. Đặt nó thành false cho phép mã thao tác biến lớp allow_reuse_address trước khi địa chỉ bị ràng buộc. Tham số use_builtin_types được chuyển đến hàm loads() và kiểm soát loại nào được xử lý khi nhận được giá trị ngày/giờ hoặc dữ liệu nhị phân; nó mặc định là sai.

Thay đổi trong phiên bản 3.3: Cờ use_builtin_types đã được thêm vào.

class xmlrpc.server.CGIXMLRPCRequestHandler(allow_none=False, encoding=None, use_builtin_types=False)¶: Tạo một phiên bản mới để xử lý các yêu cầu XML-RPC trong môi trường CGI. Các tham số allow_none và encoding được chuyển tới xmlrpc.client và kiểm soát các phản hồi XML-RPC sẽ được trả về từ máy chủ. Tham số use_builtin_types được chuyển đến hàm loads() và kiểm soát loại nào được xử lý khi nhận được giá trị ngày/giờ hoặc dữ liệu nhị phân; nó mặc định là sai.

Thay đổi trong phiên bản 3.3: Cờ use_builtin_types đã được thêm vào.

class xmlrpc.server.SimpleXMLRPCRequestHandler¶: Tạo một phiên bản xử lý yêu cầu mới. Trình xử lý yêu cầu này hỗ trợ các yêu cầu POST và sửa đổi việc ghi nhật ký để tham số logRequests thành tham số hàm tạo SimpleXMLRPCServer được tôn trọng.

Đối tượng SimpleXMLRPCServer¶

Lớp SimpleXMLRPCServer dựa trên socketserver.TCPServer và cung cấp phương tiện tạo các máy chủ XML-RPC đơn giản, độc lập.

SimpleXMLRPCServer.register_function(function=None, name=None)¶

Đăng ký một chức năng có thể đáp ứng các yêu cầu XML-RPC. Nếu name được cung cấp, nó sẽ là tên phương thức được liên kết với function, nếu không thì function.__name__ sẽ được sử dụng. name là một chuỗi và có thể chứa các ký tự không hợp pháp trong mã định danh Python, bao gồm cả ký tự dấu chấm.

Phương pháp này cũng có thể được sử dụng như một vật trang trí. Khi được sử dụng làm công cụ trang trí, name chỉ có thể được cung cấp làm đối số từ khóa để đăng ký function trong name. Nếu không có name thì function.__name__ sẽ được sử dụng.

Thay đổi trong phiên bản 3.7: register_function() có thể được sử dụng như một vật trang trí.

SimpleXMLRPCServer.register_instance(instance, allow_dotted_names=False)¶

Đăng ký một đối tượng được sử dụng để hiển thị tên phương thức chưa được đăng ký bằng register_function(). Nếu instance chứa phương thức _dispatch(), nó sẽ được gọi với tên phương thức được yêu cầu và các tham số từ yêu cầu. Zz009zz của nó là def _dispatch(self, method, params) (lưu ý rằng params không đại diện cho danh sách đối số có thể thay đổi). Nếu nó gọi một hàm cơ bản để thực hiện nhiệm vụ của mình thì hàm đó được gọi là func(*params), mở rộng danh sách tham số. Kết quả là giá trị trả về từ _dispatch() được trả về cho máy khách. Nếu instance không có phương thức _dispatch(), nó sẽ tìm kiếm thuộc tính khớp với tên của phương thức được yêu cầu.

Nếu đối số allow_dotted_names tùy chọn là đúng và phiên bản không có phương thức _dispatch() thì nếu tên phương thức được yêu cầu chứa dấu chấm, thì mỗi thành phần của tên phương thức sẽ được tìm kiếm riêng lẻ, với kết quả là thực hiện tìm kiếm phân cấp đơn giản. Sau đó, giá trị được tìm thấy từ tìm kiếm này sẽ được gọi cùng với các tham số từ yêu cầu và giá trị trả về sẽ được chuyển lại cho máy khách.

Cảnh báo

Việc bật tùy chọn allow_dotted_names cho phép kẻ xâm nhập truy cập vào các biến toàn cục của mô-đun của bạn và có thể cho phép kẻ xâm nhập thực thi mã tùy ý trên máy của bạn. Chỉ sử dụng tùy chọn này trên mạng đóng, an toàn.

SimpleXMLRPCServer.register_introspection_functions()¶: Đăng ký các chức năng xem xét nội bộ XML-RPC system.listMethods, system.methodHelp và system.methodSignature.

SimpleXMLRPCServer.register_multicall_functions()¶: Đăng ký chức năng multicall XML-RPC system.multicall.

SimpleXMLRPCRequestHandler.rpc_paths¶: Giá trị thuộc tính phải là một bộ liệt kê các phần đường dẫn hợp lệ của URL để nhận các yêu cầu XML-RPC. Các yêu cầu được đăng lên các đường dẫn khác sẽ dẫn đến lỗi HTTP 404 "không có trang như vậy". Nếu bộ dữ liệu này trống, tất cả các đường dẫn sẽ được coi là hợp lệ. Giá trị mặc định là ('/', '/RPC2').

Ví dụ về SimpleXMLRPCServer¶

Mã máy chủ:

từ xmlrpc.server nhập SimpleXMLRPCServer
từ xmlrpc.server nhập SimpleXMLRPCRequestHandler

# Restrict vào một đường dẫn cụ thể.
lớp Yêu cầuHandler (SimpleXMLRPCRequestHandler):
    rpc_paths = ('/RPC2',)

máy chủ # Create
với SimpleXMLRPCServer(('localhost', 8000),
                        requestHandler=RequestHandler) làm máy chủ:
    server.register_introspection_functions()

    # Register pow() function; điều này sẽ sử dụng giá trị của
    # pow.__name__ làm tên, chỉ là 'pow'.
    server.register_function(pow)

    # Register một hàm dưới một tên khác
    def adder_function(x, y):
        trả về x + y
    server.register_function(adder_function, 'add')

    # Register một ví dụ; tất cả các phương pháp của ví dụ là
    # published làm phương thức XML-RPC (trong trường hợp này, chỉ là 'mul').
    lớp MyFuncs:
        def mul(self, x, y):
            trả về x * y

    server.register_instance(MyFuncs())

    # Run vòng lặp chính của máy chủ
    server.serve_forever()

Mã máy khách sau sẽ gọi các phương thức được cung cấp bởi máy chủ trước đó

nhập xmlrpc.client

s = xmlrpc.client.ServerProxy('http://localhost:8000')
print(s.pow(2,3)) # Returns 2**3 = 8
print(s.add(2,3)) # Returns 5
print(s.mul(5,2)) # Returns 5*2 = 10

# Print danh sách các phương thức có sẵn
print(s.system.listMethods())

register_function() cũng có thể được sử dụng làm vật trang trí. Ví dụ về máy chủ trước có thể đăng ký các hàm theo cách trang trí:

từ xmlrpc.server nhập SimpleXMLRPCServer
từ xmlrpc.server nhập SimpleXMLRPCRequestHandler

lớp Yêu cầuHandler (SimpleXMLRPCRequestHandler):
    rpc_paths = ('/RPC2',)

với SimpleXMLRPCServer(('localhost', 8000),
                        requestHandler=RequestHandler) làm máy chủ:
    server.register_introspection_functions()

    hàm # Register pow(); điều này sẽ sử dụng giá trị của
    # pow.__name__ làm tên, chỉ là 'pow'.
    server.register_function(pow)

    # Register một hàm dưới một tên khác, sử dụng
    # register_function làm người trang trí. *name* chỉ có thể được trao
    # as một đối số từ khóa.
    @server.register_function(name='add')
    def adder_function(x, y):
        trả về x + y

    # Register một hàm trong hàm.__name__.
    @server.register_function
    def mul(x, y):
        trả về x * y

    server.serve_forever()

Ví dụ sau có trong mô-đun Lib/xmlrpc/server.py hiển thị một máy chủ cho phép các tên có dấu chấm và đăng ký chức năng gọi nhiều cuộc gọi.

Cảnh báo

Việc bật tùy chọn allow_dotted_names cho phép kẻ xâm nhập truy cập vào các biến toàn cục của mô-đun của bạn và có thể cho phép kẻ xâm nhập thực thi mã tùy ý trên máy của bạn. Chỉ sử dụng ví dụ này trong mạng khép kín, an toàn.

nhập ngày giờ dưới dạng dt

lớp Ví dụDịch vụ:
    def getData(tự):
        trả về '42'

    lớp hiện tạiThời gian:
        @staticmethod
        chắc chắn getCurrentTime():
            trả về dt.datetime.now()

với SimpleXMLRPCServer(("localhost", 8000)) làm máy chủ:
    server.register_function(pow)
    server.register_function(lambda x,y: x+y, 'add')
    server.register_instance(ExampleService(), allow_dotted_names=True)
    server.register_multicall_functions()
    print('Phục vụ XML-RPC trên cổng localhost 8000')
    thử:
        server.serve_forever()
    ngoại trừ Bàn phímInterrupt:
        print("\nĐã nhận được ngắt bàn phím, đang thoát.")
        sys.exit(0)

Bản demo exampleService này có thể được gọi từ dòng lệnh

python -m xmlrpc.server

Máy khách tương tác với máy chủ trên được bao gồm trong Lib/xmlrpc/client.py:

máy chủ = ServerProxy("http://localhost:8000")

thử:
    print(server.currentTime.getCurrentTime())
ngoại trừ Lỗi như v:
    in ("ERROR", v)

đa = MultiCall(máy chủ)
multi.getData()
đa.pow(2,9)
đa.add(1,2)
thử:
    để phản hồi trong multi():
        in (phản hồi)
ngoại trừ Lỗi như v:
    in ("ERROR", v)

Ứng dụng khách tương tác với máy chủ XMLRPC demo này có thể được gọi dưới dạng

python -m xmlrpc.client

CGIXMLRPCRequestHandler¶

Lớp CGIXMLRPCRequestHandler có thể được sử dụng để xử lý các yêu cầu XML-RPC được gửi tới tập lệnh CGI của Python.

CGIXMLRPCRequestHandler.register_function(function=None, name=None)¶

Đăng ký một chức năng có thể đáp ứng các yêu cầu XML-RPC. Nếu name được cung cấp, nó sẽ là tên phương thức được liên kết với function, nếu không thì function.__name__ sẽ được sử dụng. name là một chuỗi và có thể chứa các ký tự không hợp pháp trong mã định danh Python, bao gồm cả ký tự dấu chấm.

Phương pháp này cũng có thể được sử dụng như một vật trang trí. Khi được sử dụng làm công cụ trang trí, name chỉ có thể được cung cấp làm đối số từ khóa để đăng ký function trong name. Nếu không có name thì function.__name__ sẽ được sử dụng.

Thay đổi trong phiên bản 3.7: register_function() có thể được sử dụng như một vật trang trí.

CGIXMLRPCRequestHandler.register_instance(instance)¶: Đăng ký một đối tượng được sử dụng để hiển thị tên phương thức chưa được đăng ký bằng register_function(). Nếu phiên bản chứa phương thức _dispatch(), nó sẽ được gọi với tên phương thức được yêu cầu và các tham số từ yêu cầu; kết quả là giá trị trả về được trả về cho máy khách. Nếu phiên bản không có phương thức _dispatch(), nó sẽ tìm kiếm thuộc tính khớp với tên của phương thức được yêu cầu; nếu tên phương thức được yêu cầu chứa dấu chấm thì mỗi thành phần của tên phương thức sẽ được tìm kiếm riêng lẻ, với kết quả là thực hiện tìm kiếm phân cấp đơn giản. Sau đó, giá trị được tìm thấy từ tìm kiếm này sẽ được gọi cùng với các tham số từ yêu cầu và giá trị trả về sẽ được chuyển lại cho máy khách.

CGIXMLRPCRequestHandler.register_introspection_functions()¶: Đăng ký các hàm xem xét nội bộ XML-RPC system.listMethods, system.methodHelp và system.methodSignature.

CGIXMLRPCRequestHandler.register_multicall_functions()¶: Đăng ký chức năng multicall XML-RPC system.multicall.

CGIXMLRPCRequestHandler.handle_request(request_text=None)¶: Xử lý yêu cầu XML-RPC. Nếu request_text được cung cấp thì đó phải là dữ liệu POST do máy chủ HTTP cung cấp, nếu không nội dung của stdin sẽ được sử dụng.

Ví dụ:

lớp MyFuncs:
    def mul(self, x, y):
        trả về x * y


trình xử lý = CGIXMLRPCRequestHandler()
handler.register_function(pow)
handler.register_function(lambda x,y: x+y, 'add')
handler.register_introspection_functions()
handler.register_instance(MyFuncs())
handler.handle_request()

Tài liệu máy chủ XMLRPC¶

Các lớp này mở rộng các lớp trên để phục vụ tài liệu HTML nhằm đáp ứng các yêu cầu HTTP GET. Máy chủ có thể ở trạng thái tự do, sử dụng DocXMLRPCServer hoặc được nhúng trong môi trường CGI, sử dụng DocCGIXMLRPCRequestHandler.

class xmlrpc.server.DocXMLRPCServer(addr, requestHandler=DocXMLRPCRequestHandler, logRequests=True, allow_none=False, encoding=None, bind_and_activate=True, use_builtin_types=True)¶: Tạo một phiên bản máy chủ mới. Tất cả các tham số đều có ý nghĩa tương tự như đối với SimpleXMLRPCServer; requestHandler mặc định là DocXMLRPCRequestHandler.

Thay đổi trong phiên bản 3.3: Cờ use_builtin_types đã được thêm vào.

class xmlrpc.server.DocCGIXMLRPCRequestHandler¶: Tạo một phiên bản mới để xử lý các yêu cầu XML-RPC trong môi trường CGI.

class xmlrpc.server.DocXMLRPCRequestHandler¶: Tạo một phiên bản xử lý yêu cầu mới. Trình xử lý yêu cầu này hỗ trợ các yêu cầu XML-RPC POST, yêu cầu tài liệu GET và sửa đổi việc ghi nhật ký để tham số logRequests cho tham số hàm tạo DocXMLRPCServer được tôn trọng.

Đối tượng DocXMLRPCServer¶

Lớp DocXMLRPCServer có nguồn gốc từ SimpleXMLRPCServer và cung cấp phương tiện tạo các máy chủ XML-RPC độc lập, tự tạo tài liệu. Các yêu cầu HTTP POST được xử lý dưới dạng lệnh gọi phương thức XML-RPC. Các yêu cầu HTTP GET được xử lý bằng cách tạo tài liệu HTML kiểu pydoc. Điều này cho phép máy chủ cung cấp tài liệu dựa trên web của riêng mình.

DocXMLRPCServer.set_server_title(server_title)¶: Đặt tiêu đề được sử dụng trong tài liệu HTML được tạo. Tiêu đề này sẽ được sử dụng bên trong phần tử "title" HTML.

DocXMLRPCServer.set_server_name(server_name)¶: Đặt tên được sử dụng trong tài liệu HTML được tạo. Tên này sẽ xuất hiện ở đầu tài liệu được tạo bên trong phần tử "h1".

DocXMLRPCServer.set_server_documentation(server_documentation)¶: Đặt mô tả được sử dụng trong tài liệu HTML được tạo. Mô tả này sẽ xuất hiện dưới dạng một đoạn văn, bên dưới tên máy chủ, trong tài liệu.

DocCGIXMLRPCRequestHandler¶

Lớp DocCGIXMLRPCRequestHandler có nguồn gốc từ CGIXMLRPCRequestHandler và cung cấp một phương tiện để tạo các tập lệnh XML-RPC CGI tự ghi lại. Các yêu cầu HTTP POST được xử lý dưới dạng lệnh gọi phương thức XML-RPC. Các yêu cầu HTTP GET được xử lý bằng cách tạo tài liệu HTML kiểu pydoc. Điều này cho phép máy chủ cung cấp tài liệu dựa trên web của riêng mình.

DocCGIXMLRPCRequestHandler.set_server_title(server_title)¶: Đặt tiêu đề được sử dụng trong tài liệu HTML được tạo. Tiêu đề này sẽ được sử dụng bên trong phần tử "title" HTML.

DocCGIXMLRPCRequestHandler.set_server_name(server_name)¶: Đặt tên được sử dụng trong tài liệu HTML được tạo. Tên này sẽ xuất hiện ở đầu tài liệu được tạo bên trong phần tử "h1".

DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)¶: Đặt mô tả được sử dụng trong tài liệu HTML được tạo. Mô tả này sẽ xuất hiện dưới dạng một đoạn văn, bên dưới tên máy chủ, trong tài liệu.

`xmlrpc.server` --- Máy chủ XML-RPC cơ bản¶

Đối tượng SimpleXMLRPCServer¶

Ví dụ về SimpleXMLRPCServer¶

CGIXMLRPCRequestHandler¶

Tài liệu máy chủ XMLRPC¶

Đối tượng DocXMLRPCServer¶

DocCGIXMLRPCRequestHandler¶

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này

xmlrpc.server --- Máy chủ XML-RPC cơ bản¶

Đối tượng SimpleXMLRPCServer¶

Ví dụ về SimpleXMLRPCServer¶

CGIXMLRPCRequestHandler¶

Tài liệu máy chủ XMLRPC¶

Đối tượng DocXMLRPCServer¶

DocCGIXMLRPCRequestHandler¶

`xmlrpc.server` --- Máy chủ XML-RPC cơ bản¶