dagster-dingtalk 0.1.10b1__py3-none-any.whl → 0.1.11__py3-none-any.whl

dagster_dingtalk/__init__.py

@@ -3,6 +3,7 @@ from dagster._core.libraries import DagsterLibraryRegistry
 
 from dagster_dingtalk.resources import DingTalkAppResource
 from dagster_dingtalk.resources import DingTalkWebhookResource
+from dagster_dingtalk.app_client import DingTalkClient as DingTalkAppClient
 # from dagster_dingtalk.operations import DingTalkWebhookOp
 from dagster_dingtalk.version import __version__
 

dagster_dingtalk/app_client.py

@@ -15,48 +15,77 @@ class DingTalkClient:
         self.app_name: str|None = app_name
         self.agent_id: int|None = agent_id
         self.client_id: str = client_id
-        self.client_secret: str = client_secret
+        self.__client_secret: str = client_secret
         self.robot_code: str = client_id
 
-        access_token: str = self._get_access_token()
+        access_token: str = self.__get_access_token()
         self.api: Client = Client(base_url="https://api.dingtalk.com/", headers={"x-acs-dingtalk-access-token": access_token})
         self.oapi: Client = Client(base_url="https://oapi.dingtalk.com/", params={"access_token": access_token})
 
         self.智能人事 = 智能人事_API(self)
         self.通讯录管理 = 通讯录管理_API(self)
         self.文档文件 = 文档文件_API(self)
+        self.互动卡片 = 互动卡片_API(self)
 
-    def _get_access_token(self) -> str:
+    def __get_access_token(self) -> str:
         access_token_cache = Path("/tmp/.dingtalk_cache")
+        all_access_token: dict = {}
+        access_token: str|None = None
+        expire_in: int = 0
+        renew_reason = None
 
-        try:
-            with open(access_token_cache, 'rb') as f:
-                all_access_token: Dict[str, Tuple[str, int]] = pickle.loads(f.read())
-                access_token, expire_in = all_access_token.get(self.app_id, ('', 0))
-        except Exception as e:
-            print(e)
-            all_access_token = {}
-            access_token, expire_in = all_access_token.get(self.app_id, ('', 0))
+        # 从缓存中读取
+        if not access_token_cache.exists():
+            renew_reason = f"鉴权缓存不存在"
+        else:
+            try:
+                with open(access_token_cache, 'rb') as f:
+                    cache_file = f.read()
+            except Exception as e:
+                logging.error(e)
+                cache_file = None
+                renew_reason = "鉴权缓存读取错误"
+
+        if cache_file:
+            try:
+                all_access_token = pickle.loads(cache_file)
+            except pickle.PickleError:
+                renew_reason = f"鉴权缓存解析错误"
+
+        if all_access_token:
+            app_access_token = all_access_token.get(self.app_id)
+            access_token = app_access_token.get('access_token')
+            expire_in = app_access_token.get('expire_in')
+        else:
+            renew_reason = f"鉴权缓存不存在该应用 {self.app_name}<{self.app_id}>"
 
-        if access_token and expire_in < int(time.time()):
+        if not access_token:
+            renew_reason = F"应用 {self.app_name}<{self.app_id}> 的鉴权缓存无效"
+        if expire_in < int(time.time()):
+            renew_reason = F"应用 {self.app_name}<{self.app_id}> 的鉴权缓存过期"
+
+        if renew_reason is None:
             return access_token
         else:
-            logging.warning(f"应用{self.app_name}<{self.app_id}> 鉴权缓存过期或不存在，正在重新获取...")
+            logging.warning(renew_reason)
             response = Client().post(
                 url="https://api.dingtalk.com/v1.0/oauth2/accessToken",
-                json={"appKey": self.client_id, "appSecret": self.client_secret},
+                json={"appKey": self.client_id, "appSecret": self.__client_secret},
             )
             access_token:str = response.json().get("accessToken")
             expire_in:int = response.json().get("expireIn") + int(time.time()) - 60
             with open(access_token_cache, 'wb') as f:
-                all_access_token[self.app_id] = (access_token, expire_in)
+                all_access_token[self.app_id] = {
+                    "access_token": access_token,
+                    "expire_in": expire_in,
+                }
                 f.write(pickle.dumps(all_access_token))
             return access_token
 
-
 # noinspection NonAsciiCharacters
 class 智能人事_API:
     def __init__(self, _client:DingTalkClient):
+        self.__client:DingTalkClient = _client
         self.花名册 = 智能人事_花名册_API(_client)
         self.员工管理 = 智能人事_员工管理_API(_client)
 
@@ -84,7 +113,6 @@ class 智能人事_花名册_API:
 
 # noinspection NonAsciiCharacters
 class 智能人事_员工管理_API:
-
     def __init__(self, _client:DingTalkClient):
         self.__client:DingTalkClient = _client
 
@@ -126,7 +154,17 @@ class 智能人事_员工管理_API:
 # noinspection NonAsciiCharacters
 class 通讯录管理_API:
     def __init__(self, _client:DingTalkClient):
-        self.__client = _client
+        self.__client:DingTalkClient = _client
+        self.用户管理 = 通讯录管理_用户管理_API(_client)
+        self.部门管理 = 通讯录管理_部门管理_API(_client)
+
+    def 查询用户详情(self, user_id:str, language:str = "zh_CN"):
+        return self.用户管理.查询用户详情(user_id, language)
+
+# noinspection NonAsciiCharacters
+class 通讯录管理_用户管理_API:
+    def __init__(self, _client:DingTalkClient):
+        self.__client:DingTalkClient = _client
 
     def 查询用户详情(self, user_id:str, language:str = "zh_CN") -> dict:
         response = self.__client.oapi.post(url="/topapi/v2/user/get", json={"language": language, "userid": user_id})
@@ -139,17 +177,158 @@ class 通讯录管理_API:
         response = self.__client.api.get(url="/v1.0/contact/empLeaveRecords", params=params)
         return response.json()
 
+# noinspection NonAsciiCharacters
+class 通讯录管理_部门管理_API:
+    def __init__(self, _client:DingTalkClient):
+        self.__client:DingTalkClient = _client
+
+    def 获取部门详情(self, dept_id: int, language:str = "zh_CN") -> dict:
+        """
+        调用本接口，根据部门ID获取指定部门详情。
+
+        https://open.dingtalk.com/document/orgapp/query-department-details0-v2
+
+        :param dept_id: 部门 ID ，根部门 ID 为 1。
+        :param language: 通讯录语言。zh_CN en_US
+        """
+        response = self.__client.oapi.post(
+            url="/topapi/v2/department/get",
+            json={"language": language, "dept_id": dept_id}
+        )
+        return response.json()
+
+    def 获取部门列表(self, dept_id: int, language:str = "zh_CN"):
+        """
+        调用本接口，获取下一级部门基础信息。
+
+        https://open.dingtalk.com/document/orgapp/obtain-the-department-list-v2
+
+        :param dept_id: 部门 ID ，根部门 ID 为 1。
+        :param language: 通讯录语言。zh_CN en_US
+        """
+        response = self.__client.oapi.post(
+            url="/topapi/v2/department/listsub",
+            json={"language": language, "dept_id": dept_id}
+        )
+        return response.json()
+
 # noinspection NonAsciiCharacters
 class 文档文件_API:
     def __init__(self, _client:DingTalkClient):
+        self.__client:DingTalkClient = _client
         self.媒体文件 = 文档文件_媒体文件_API(_client)
 
 # noinspection NonAsciiCharacters
 class 文档文件_媒体文件_API:
     def __init__(self, _client:DingTalkClient):
-        self.__client = _client
+        self.__client:DingTalkClient = _client
 
     def 上传媒体文件(self, file_path:Path|str, media_type:Literal['image', 'voice', 'video', 'file']) -> dict:
+        """
+        调用本接口，上传图片、语音媒体资源文件以及普通文件，接口返回媒体资源标识 media_id。
+
+        https://open.dingtalk.com/document/orgapp/upload-media-files
+
+        :param file_path: 本地文件路径
+        :param media_type: 媒体类型，支持 'image', 'voice', 'video', 'file'
+
+        :return:
+            {
+                "errcode": 0,
+                "errmsg": "ok",
+                "media_id": "$iAEKAqDBgTNAk",
+                "created_at": 1605863153573,
+                "type": "image"
+            }
+        """
         with open(file_path, 'rb') as f:
             response = self.__client.oapi.post(url=f"/media/upload?type={media_type}", files={'media': f})
         return response.json()
+
+# noinspection NonAsciiCharacters
+class 互动卡片_API:
+    def __init__(self, _client:DingTalkClient):
+        self.__client:DingTalkClient = _client
+
+    def 创建并投放卡片(
+            self, search_type_name: str, search_desc: str, card_template_id: str, card_param_map: dict,
+            alert_content: str, open_space_ids: List[str], out_track_id: str, support_forward: bool = True,
+            call_back_type: str = "STREAM", expired_time_millis:int = 0
+    ) -> dict:
+        """
+        创建并投放卡片。当前仅支持 IM群聊, IM机器人单聊, 吊顶 三种场域类型。
+
+        https://open.dingtalk.com/document/orgapp/create-and-deliver-cards
+
+        :param card_template_id: 卡片模板 ID
+        :param open_space_ids: 卡片投放场域 Id
+        :param out_track_id: 卡片唯一标识
+        :param card_param_map: 卡片数据
+        :param search_type_name: 卡片类型名
+        :param search_desc: 卡片消息展示
+        :param alert_content: 通知内容
+        :param call_back_type: 回调模式
+        :param support_forward: 是否支持转发
+        :param expired_time_millis: 吊顶投放过期时间。当投放内容为吊顶时必须传参。
+        """
+
+        open_space_id = f"dtv1.card//{';'.join(open_space_ids)}"
+
+        payload = {
+            "cardTemplateId": card_template_id,
+            "outTrackId": out_track_id,
+            "openSpaceId": open_space_id,
+            "callbackType": call_back_type,
+            "cardData": {"cardParamMap": card_param_map}
+        }
+
+        open_space_model = {
+                "supportForward": support_forward,
+                "searchSupport": {"searchTypeName": search_type_name, "searchDesc": search_desc},
+                "notification": {"alertContent": alert_content, "notificationOff": False}
+            }
+
+        if 'IM_GROUP' in open_space_id.upper():
+            payload["imGroupOpenSpaceModel"] = open_space_model
+            payload["imGroupOpenDeliverModel"] = {"robotCode": self.__client.robot_code}
+
+        if 'IM_ROBOT' in open_space_id.upper():
+            payload["imRobotOpenSpaceModel"] = open_space_model
+            payload["imRobotOpenDeliverModel"] = {"spaceType": "IM_ROBOT", "robotCode": self.__client.robot_code}
+
+        if 'ONE_BOX' in open_space_id.upper():
+            if expired_time_millis == 0:
+                expired_time_millis = int(time.time()+3600)*1000
+            payload["topOpenSpaceModel"] = {"spaceType": "ONE_BOX"}
+            payload["topOpenDeliverModel"] = {"platforms": ["android","ios","win","mac"], "expiredTimeMillis": expired_time_millis,}
+
+        response = self.__client.api.post(
+            url="/v1.0/card/instances/createAndDeliver",
+            json=payload
+        )
+
+        return response.json()
+
+    def 更新卡片(self, out_track_id: str, card_param_map: dict, update_card_data_by_key:bool=True) -> dict:
+        """
+        调用本接口，实现主动更新卡片数据。
+
+        https://open.dingtalk.com/document/orgapp/interactive-card-update-interface
+
+        :param out_track_id: 外部卡片实例Id。
+        :param card_param_map: 卡片模板内容。
+        :param update_card_data_by_key: True-按 key 更新 cardData 数据 False-覆盖更新 cardData 数据
+        :return:
+            {success: bool, result: bool}
+        """
+
+        response = self.__client.api.put(
+            url="/v1.0/card/instances",
+            json={
+                "outTrackId": out_track_id,
+                "cardData": {"cardParamMap": card_param_map},
+                "cardUpdateOptions": {"updateCardDataByKey": update_card_data_by_key}
+            }
+        )
+
+        return response.json()

dagster_dingtalk/resources.py

@@ -7,27 +7,123 @@ import urllib.parse
 from typing import Optional, Tuple, List, Literal
 import httpx
 from pydantic import Field
-from app_client import DingTalkClient
+from .app_client import DingTalkClient
 from dagster import ConfigurableResource, InitResourceContext
 
 
+DINGTALK_WEBHOOK_EXCEPTION_SOLUTIONS = {
+    "-1": "\n系统繁忙，请稍后重试",
+    "40035": "\n缺少参数 json，请补充消息json",
+    "43004": "\n无效的HTTP HEADER Content-Type，请设置具体的消息参数",
+    "400013": "\n群已被解散，请向其他群发消息",
+    "400101": "\naccess_token不存在，请确认access_token拼写是否正确",
+    "400102": "\n机器人已停用，请联系管理员启用机器人",
+    "400105": "\n不支持的消息类型，请使用文档中支持的消息类型",
+    "400106": "\n机器人不存在，请确认机器人是否在群中",
+    "410100": "\n发送速度太快而限流，请降低发送速度",
+    "430101": "\n含有不安全的外链，请确认发送的内容合法",
+    "430102": "\n含有不合适的文本，请确认发送的内容合法",
+    "430103": "\n含有不合适的图片，请确认发送的内容合法",
+    "430104": "\n含有不合适的内容，请确认发送的内容合法",
+    "310000": "\n消息校验未通过，请查看机器人的安全设置",
+}
+
+
+class DingTalkWebhookException(Exception):
+    def __init__(self, errcode, errmsg):
+        self.errcode = errcode
+        self.errmsg = errmsg
+        super().__init__(f"DingTalkWebhookError {errcode}: {errmsg} {DINGTALK_WEBHOOK_EXCEPTION_SOLUTIONS.get(errcode)}")
+
+
 class DingTalkWebhookResource(ConfigurableResource):
     """
-    定义一个钉钉群 Webhook 机器人资源，可以用来发送各类通知。
+    该资源允许定义单个钉钉自定义机器人的 Webhook 端点，以便于发送文本、Markdown、Link、 ActionCard、FeedCard 消息，消息具体样式可参考
+    [钉钉开放平台 | 自定义机器人发送消息的消息类型](https://open.dingtalk.com/document/orgapp/custom-bot-send-message-type)。
+
+    ### 配置项:
+
+    - **access_token** (str):
+        机器人 Webhook 地址中的 access_token 值。
+    - **secret** (str, optional):
+        如使用加签安全配置，则需传签名密钥。默认值为 None。
+    - **alias** (str, optional):
+        如提供别名，可以在使用 `MultiDingTalkWebhookResource` 中使用别名进行 webhook 选择。默认值为 None。
+    - **base_url** (str, optional):
+        通用地址，一般无需更改。默认值为 “https://oapi.dingtalk.com/robot/send”。
+
+    ### 用例:
+
+    1. 使用单个资源：
+
+    ```python
+    from dagster_dingtalk import DingTalkWebhookResource
+
+    @op(required_resource_keys={"dingtalk_webhook"}, ins={"text": In(str)})
+    def op_send_text(context:OpExecutionContext, text:str):
+        dingtalk_webhook:DingTalkWebhookResource = context.resources.dingtalk_webhook
+        result = dingtalk.send_text(text)
+
+    @job
+    def job_send_text():
+        op_send_text
+
+    defs = Definitions(
+        jobs=job_user_info,
+        resources={"dingtalk_webhook": DingTalkWebhookResource(access_token = "<access_token>", secret = "<secret>")}
+    )
+    ```
+
+    2. 启动时动态构建企业内部应用资源, 可参考 [Dagster文档 | 在启动时配置资源](https://docs.dagster.io/concepts/resources#configuring-resources-at-launch-time)
+
+    ```python
+    from dagster_dingtalk import DingTalkWebhookResource
 
-    钉钉API文档：
-    https://open.dingtalk.com/document/orgapp/custom-bot-send-message-type
+    @op(required_resource_keys={"dingtalk_webhook"}, ins={"text": In(str)})
+    def op_send_text(context:OpExecutionContext, text:str):
+        dingtalk_webhook:DingTalkWebhookResource = context.resources.dingtalk_webhook
+        result = dingtalk.send_text(text)
+
+    @job
+    def job_send_text():
+        op_send_text
+
+    dingtalk_webhooks = {
+        "Group1" : DingTalkWebhookResource(access_token="<access_token>", secret="<secret>", alias="Group1"),
+        "Group2" : DingTalkWebhookResource(access_token="<access_token>", secret="<secret>", alias="Group2")
+    }
+
+    defs = Definitions(jobs=job_send_text, resources={"dingtalk_webhook": DingTalkWebhookResource.configure_at_launch()})
+
+    @schedule(cron_schedule="20 9 * * *", job=job_send_text)
+    def schedule_user_info():
+        return RunRequest(run_config=RunConfig(
+            ops={"op_send_text": {"inputs": {"text": "This a test text."}}},
+            resources={"dingtalk": dingtalk_webhooks["Group1"]},
+        ))
+    ```
+
+    ### 注意:
+
+    应该永远避免直接将密钥字符串直接配置给资源，这会导致在 dagster 前端用户界面暴露密钥。
+    应当从环境变量中读取密钥。你可以在代码中注册临时的环境变量，或从系统中引入环境变量。
+
+    ```python
+    import os
+    from dagster_dingtalk import DingTalkWebhookResource
+
+    # 直接在代码中注册临时的环境变量
+    os.environ.update({'access_token': "<access_token>"})
+    os.environ.update({'secret': "<secret>"})
+
+    webhook = DingTalkWebhookResource(access_token=EnvVar("access_token"), secret=EnvVar("secret"))
 
-    Args:
-        access_token (str): 机器人 Webhook 地址中的 access_token 值。
-        secret (str, optional): 如使用加签安全配置，则需传签名密钥。默认值为 None。
-        alias (str, optional): 如提供别名，可以在使用 `MultiDingTalkWebhookResource` 中使用别名进行 webhook 选择。默认值为 None。
-        base_url (str, optional): 通用地址，一般无需更改。默认值为 “https://oapi.dingtalk.com/robot/send”。
 
     """
+
     access_token: str = Field(description="Webhook地址中的 access_token 部分")
     secret: Optional[str] = Field(default=None, description="如使用加签安全配置，需传签名密钥")
-    alias: Optional[str] = Field(default=None, description="如提供别名，将来可以使用别名进行选择")
+    alias: Optional[str] = Field(default=None, description="别名，标记用，无实际意义")
     base_url: str = Field(default="https://oapi.dingtalk.com/robot/send", description="Webhook的通用地址，无需更改")
 
     def webhook_url(self):
@@ -37,7 +133,7 @@ class DingTalkWebhookResource(ConfigurableResource):
         钉钉API文档：
         https://open.dingtalk.com/document/robots/custom-robot-access
 
-        Returns:
+        :return:
             str: Webhook URL
         """
         if self.secret is None:
@@ -55,14 +151,28 @@ class DingTalkWebhookResource(ConfigurableResource):
         """
         从文本截取前12个字符作为标题，并清理其中的 Markdown 格式字符。
 
-        Args:
-            text: 原文
+        :param text: 原文
 
-        Returns:
+        :return:
             str: 标题
         """
         return re.sub(r'[\n#>* ]', '', text[:12])
 
+    @staticmethod
+    def __handle_response(response):
+        """
+        处理钉钉 Webhook API 响应，根据 errcode 抛出相应的异常
+
+        :param response: 钉钉Webhook API响应的JSON数据
+        """
+        errcode = response.json().get("errcode")
+        errmsg = response.json().get("errmsg")
+
+        if errcode == "0":
+            return True
+        else:
+            raise DingTalkWebhookException(errcode, errmsg)
+
     def send_text(self, text: str,
                   at_mobiles:List[str]|None = None, at_user_ids:List[str]|None = None, at_all:bool = False):
         """
@@ -71,18 +181,21 @@ class DingTalkWebhookResource(ConfigurableResource):
         钉钉API文档：
         https://open.dingtalk.com/document/orgapp/custom-bot-send-message-type
 
-        Args:
-            text (str): 待发送文本
-            at_mobiles (List[str], optional): 需要 @ 的用户手机号。默认值为 None
-            at_user_ids (List[str], optional): 需要 @ 的用户 UserID。默认值为 None
-            at_all (bool, optional): 是否 @ 所有人。默认值为 False
+        :param str text: 待发送文本
+        :param List[str],optional at_mobiles: 需要 @ 的用户手机号。默认值为 None
+        :param List[str],optional at_user_ids: 需要 @ 的用户 UserID。默认值为 None
+        :param bool,optional at_all: 是否 @ 所有人。默认值为 False
+
+        :raise DingTalkWebhookException:
+
         """
         at = {"isAtAll": at_all}
         if at_user_ids:
             at["atUserIds"] = at_user_ids
         if at_mobiles:
             at["atMobiles"] = at_mobiles
-        httpx.post(url=self.webhook_url(), json={"msgtype": "text", "text": {"content": text}, "at": at})
+        response = httpx.post(url=self.webhook_url(), json={"msgtype": "text", "text": {"content": text}, "at": at})
+        self.__handle_response(response)
 
     def send_link(self, text: str, message_url:str, title:str|None = None, pic_url:str = ""):
         """
@@ -91,31 +204,26 @@ class DingTalkWebhookResource(ConfigurableResource):
         钉钉API文档：
         https://open.dingtalk.com/document/orgapp/custom-bot-send-message-type
 
-        Args:
-            text (str): 待发送文本
-            message_url (str): 链接的 Url
-            title (str, optional): 标题，在通知和被引用时显示的简短信息。默认从文本中生成。
-            pic_url (str, optional): 图片的 Url，默认为 None
+        :param str text: 待发送文本
+        :param str message_url: 链接的 Url
+        :param str,optional title: 标题，在通知和被引用时显示的简短信息。默认从文本中生成。
+        :param str,optional pic_url: 图片的 Url，默认为 None
+
+        :raise DingTalkWebhookException:
         """
         title = title or self._gen_title(text)
-        httpx.post(
+        response = httpx.post(
             url=self.webhook_url(),
             json={"msgtype": "link", "link": {"title": title, "text": text, "picUrl": pic_url, "messageUrl": message_url}}
         )
+        self.__handle_response(response)
 
     def send_markdown(self, text: List[str]|str, title:str|None = None,
                       at_mobiles:List[str]|None = None, at_user_ids:List[str]|None = None, at_all:bool = False):
         """
         发送 Markdown 消息。支持的语法有：
-            # 一级标题
-            ## 二级标题
-            ### 三级标题
-            #### 四级标题
-            ##### 五级标题
-            ###### 六级标题
-            > 引用
-            **加粗**
-            *斜体*
+            # 一级标题  ## 二级标题  ### 三级标题  #### 四级标题  ##### 五级标题  ###### 六级标题
+            > 引用  **加粗**  *斜体*
             [链接跳转](https://example.com/doc.html)
             ![图片预览](https://example.com/pic.jpg)
             - 无序列表
@@ -124,12 +232,13 @@ class DingTalkWebhookResource(ConfigurableResource):
         钉钉API文档：
         https://open.dingtalk.com/document/orgapp/custom-bot-send-message-type
 
-        Args:
-            text (str): 待发送文本
-            title (str, optional): 标题，在通知和被引用时显示的简短信息。默认从文本中生成。
-            at_mobiles (List[str], optional): 需要 @ 的用户手机号。默认值为 None
-            at_user_ids (List[str], optional): 需要 @ 的用户 UserID。默认值为 None
-            at_all (bool, optional): 是否 @ 所有人。默认值为 False
+        :param str text: 待发送文本
+        :param str,optional title: 标题，在通知和被引用时显示的简短信息。默认从文本中生成。
+        :param List[str],optional at_mobiles: 需要 @ 的用户手机号。默认值为 None
+        :param List[str],optional at_user_ids: 需要 @ 的用户 UserID。默认值为 None
+        :param bool,optional at_all: 是否 @ 所有人。默认值为 False
+
+        :raise DingTalkWebhookException:
         """
         text = text if isinstance(text, str) else "\n\n".join(text)
         title = title or self._gen_title(text)
@@ -138,43 +247,44 @@ class DingTalkWebhookResource(ConfigurableResource):
             at["atUserIds"] = at_user_ids
         if at_mobiles:
             at["atMobiles"] = at_mobiles
-        httpx.post(url=self.webhook_url(),json={"msgtype": "markdown", "markdown": {"title": title, "text": text}, "at": at})
+        response = httpx.post(url=self.webhook_url(),json={"msgtype": "markdown", "markdown": {"title": title, "text": text}, "at": at})
+        self.__handle_response(response)
 
     def send_action_card(self, text: List[str]|str, title:str|None = None, btn_orientation:Literal["0","1"] = "0",
                          single_jump:Tuple[str,str]|None = None, btns_jump:List[Tuple[str,str]]|None = None):
         """
         发送跳转 ActionCard 消息。
 
-        Args:
-            text (str): 待发送文本，支持 Markdown 部分语法。
-            title (str, optional): 标题，在通知和被引用时显示的简短信息。默认从文本中生成。
-            btn_orientation (str, optional):  按钮排列方式，0-按钮竖直排列，1-按钮横向排列。默认值为 "0"
-            single_jump(Tuple[str,str], optional): 传此参数为单个按钮，元组内第一项为按钮的标题，第二项为按钮链接。
-            btns_jump(Tuple[str,str], optional): 传此参数为多个按钮，元组内第一项为按钮的标题，第二项为按钮链接。
+        **注意：**
+        同时传 `single_jump` 和 `btns_jump`，仅 `single_jump` 生效。
 
-        Notes:
-            同时传 single_jump 和 btns_jump，仅 single_jump 生效。
+        :param str text: 待发送文本，支持 Markdown 部分语法。
+        :param str,optional title: 标题，在通知和被引用时显示的简短信息。默认从文本中生成。
+        :param str,optional btn_orientation: 按钮排列方式，0-按钮竖直排列，1-按钮横向排列。默认值为 "0"
+        :param Tuple[str,str],optional single_jump: 传此参数为单个按钮，元组内第一项为按钮的标题，第二项为按钮链接。
+        :param Tuple[str,str],optional btns_jump: 传此参数为多个按钮，元组内第一项为按钮的标题，第二项为按钮链接。
 
+        :raise DingTalkWebhookException:
         """
         text = text if isinstance(text, str) else "\n\n".join(text)
         title = title or self._gen_title(text)
         action_card = {"title": title, "text": text, "btnOrientation": str(btn_orientation)}
+
         if single_jump:
             action_card["singleTitle"], action_card["singleURL"] = single_jump
-            httpx.post(url=self.webhook_url(), json={"msgtype": "actionCard", "actionCard": action_card})
-        elif btns_jump:
+        if btns_jump:
             action_card["btns"] = [{"title": action_title, "actionURL": action_url} for action_title, action_url in btns_jump]
-            httpx.post(url=self.webhook_url(), json={"msgtype": "actionCard", "actionCard": action_card})
-        else:
-            pass
+
+        response = httpx.post(url=self.webhook_url(), json={"msgtype": "actionCard", "actionCard": action_card})
+        self.__handle_response(response)
 
     def send_feed_card(self, *args:Tuple[str,str,str]):
         """
         发送 FeedCard 消息。
 
-        Args:
-            args (Tuple[str,str,str]): 可以传入任意个具有三个元素的元组，分别为 (标题, 跳转链接, 缩略图链接)
+        :param Tuple[str,str,str],optional args: 可以传入任意个具有三个元素的元组，分别为 `(标题, 跳转链接, 缩略图链接)`
 
+        :raise DingTalkWebhookException:
         """
         for a in args:
             print(a)
@@ -182,23 +292,100 @@ class DingTalkWebhookResource(ConfigurableResource):
             {"title": title, "messageURL": message_url, "picURL": pic_url}
             for title, message_url, pic_url in args
         ]
-        httpx.post(url=self.webhook_url(), json={"msgtype": "feedCard", "feedCard": {"links": links_data}})
+        response = httpx.post(url=self.webhook_url(), json={"msgtype": "feedCard", "feedCard": {"links": links_data}})
+        self.__handle_response(response)
 
 
 class DingTalkAppResource(ConfigurableResource):
     """
     [钉钉服务端 API](https://open.dingtalk.com/document/orgapp/api-overview) 企业内部应用部分的第三方封装。
-    通过此资源，可以调用部分钉钉服务端API。
 
-    Notes:
-        不包含全部的API端点。
+    通过此资源，可以调用部分钉钉服务端 API。具体封装的 API 可以在 IDE 中通过引入 `DingTalkAppClient` 类来查看 IDE 提示：
+
+    `from dagster_dingtalk import DingTalkAppClient`
+
+    ### 配置项:
+
+    - **AppID** (str):
+        应用应用唯一标识 AppID，作为缓存标识符使用。不传入则不缓存鉴权。
+    - **AgentID** (int, optional):
+        原企业内部应用 AgentId ，部分 API 会使用到。默认值为 None
+    - **AppName** (str, optional):
+        应用名。
+    - **ClientId** (str):
+        应用的 Client ID ，原 AppKey 和 SuiteKey
+    - **ClientSecret** (str):
+        应用的 Client Secret ，原 AppSecret 和 SuiteSecret
+
+    ### 用例:
+
+    1. 使用单一的企业内部应用资源。
+
+    ```python
+    from dagster_dingtalk import DingTalkAppResource
+
+    @op(required_resource_keys={"dingtalk"}, ins={"user_id": In(str)})
+    def op_user_info(context:OpExecutionContext, user_id:str):
+        dingtalk:DingTalkAppClient = context.resources.dingtalk
+        result = dingtalk.通讯录管理.用户管理.查询用户详情(user_id).get('result')
+        context.log.info(result)
+
+    @job
+    def job_user_info():
+        op_user_info
+
+    defs = Definitions(jobs=job_user_info, resources={
+        "dingtalk": DingTalkAppResource(
+            AppID = "<the-app-id>",
+            ClientId = "<the-client-id>",
+            ClientSecret = EnvVar("<the-client-secret-env-name>"),
+        )
+    })
+    ```
+
+    2. 启动时动态构建企业内部应用资源, 可参考 [Dagster文档 | 在启动时配置资源](https://docs.dagster.io/concepts/resources#configuring-resources-at-launch-time)
+
+    ```python
+    from dagster_dingtalk import DingTalkAppResource
+
+    @op(required_resource_keys={"dingtalk"}, ins={"user_id": In(str)})
+    def op_user_info(context:OpExecutionContext, user_id:str):
+        dingtalk:DingTalkAppClient = context.resources.dingtalk
+        result = dingtalk.通讯录管理.用户管理.查询用户详情(user_id).get('result')
+        context.log.info(result)
+
+    @job
+    def job_user_info():
+        op_user_info()
+
+    dingtalk_apps = {
+        "App1" : DingTalkAppResource(
+            AppID = "<app-1-app-id>",
+            ClientId = "<app-1-client-id>",
+            ClientSecret = EnvVar("<app-1-client-secret-env-name>"),
+        ),
+        "App2" : DingTalkAppResource(
+            AppID = "<app-2-app-id>",
+            ClientId = "<app-2-client-id>",
+            ClientSecret = EnvVar("<app-2-client-secret-env-name>"),
+        )
+    }
+
+    defs = Definitions(jobs=job_user_info, resources={"dingtalk": DingTalkAppResource.configure_at_launch()})
+
+    @schedule(cron_schedule="20 9 * * *", job=job_user_info)
+    def schedule_user_info():
+        return RunRequest(run_config=RunConfig(
+            ops={"op_user_info": {"inputs": {"user_id": "<the-user-id>"}}},
+            resources={"dingtalk": dingtalk_apps["App1"]},
+        ))
+    ```
+
+    ### 注意:
+
+    应该永远避免直接将密钥字符串直接配置给资源，这会导致在 dagster 前端用户界面暴露密钥。
+    应当从环境变量中读取密钥。你可以在代码中注册临时的环境变量，或从系统中引入环境变量。
 
-    Args:
-        AppID (str): 应用应用唯一标识 AppID，作为缓存标识符使用。不传入则不缓存鉴权。
-        AgentID (int, optional): 原企业内部应用 AgentId ，部分 API 会使用到。默认值为 None
-        AppName (str, optional): 应用名。
-        ClientId (str): 应用的 Client ID ，原 AppKey 和 SuiteKey
-        ClientSecret (str): 应用的 Client Secret ，原 AppSecret 和 SuiteSecret
     """
 
     AppID: str = Field(description="应用应用唯一标识 AppID，作为缓存标识符使用。不传入则不缓存鉴权。")
@@ -212,6 +399,11 @@ class DingTalkAppResource(ConfigurableResource):
         return False
 
     def create_resource(self, context: InitResourceContext) -> DingTalkClient:
+        """
+        返回一个 `DingTalkClient` 实例。
+        :param context:
+        :return:
+        """
         return DingTalkClient(
             app_id=self.AppID,
             agent_id=self.AgentID,

dagster_dingtalk/version.py

@@ -1 +1 @@
-__version__ = "0.1.10b1"
+__version__ = "0.1.11"

{dagster_dingtalk-0.1.10b1.dist-info → dagster_dingtalk-0.1.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dagster-dingtalk
-Version: 0.1.10b1
+Version: 0.1.11
 Summary: A dagster plugin for the DingTalk
 Author: YiZixuan
 Author-email: sqkkyzx@qq.com

dagster_dingtalk-0.1.11.dist-info/RECORD

@@ -0,0 +1,8 @@
+dagster_dingtalk/__init__.py,sha256=X7r8JoydXOsT9Sis4rBpVSKQeKJnnZ_t_qFae-ASF7E,466
+dagster_dingtalk/app_client.py,sha256=xZ9NcVZuWvz7S2thm4B1h4aFiBXmUnkp5nK5N_k7HwE,14011
+dagster_dingtalk/operations.py,sha256=3cCZCxh-dAdzzb75WCTKVdzeMV8yu_JJpIeULS7XaNg,761
+dagster_dingtalk/resources.py,sha256=XXGRub47EZY2MfAsGhyEZ_Joh_D-BMFNh_jXCVPx6tU,17255
+dagster_dingtalk/version.py,sha256=nllDrH0jyChMuuYrK0CC55iTBKUNTUjejtcwxyUF2EQ,23
+dagster_dingtalk-0.1.11.dist-info/METADATA,sha256=AqQfS-lsnBW-PBoad9xIsZei9b995Yf4SJhaHq1YQ7c,1221
+dagster_dingtalk-0.1.11.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+dagster_dingtalk-0.1.11.dist-info/RECORD,,

dagster_dingtalk-0.1.10b1.dist-info/RECORD

@@ -1,8 +0,0 @@
-dagster_dingtalk/__init__.py,sha256=TUfdRP1n-tifjBuC9ugDxzeNu-BtjmX2fEFDgTitHeo,390
-dagster_dingtalk/app_client.py,sha256=nti06ZM_LKvdDkHryt1-beIKZrYcOkUKDznXXnqn8qg,6747
-dagster_dingtalk/operations.py,sha256=3cCZCxh-dAdzzb75WCTKVdzeMV8yu_JJpIeULS7XaNg,761
-dagster_dingtalk/resources.py,sha256=SuQiNvq50eqdGT3bT0eiQ7whv6CGp8rZsqfHL6gBtf4,9780
-dagster_dingtalk/version.py,sha256=Nw9m62L0Jey5qchmcQFQeIRAFUlcjZewmyhYlfs0pG0,25
-dagster_dingtalk-0.1.10b1.dist-info/METADATA,sha256=m6GrwJ60HSHFP4UfVSO6y5ybcIwFs_8TXNowkjjKRnw,1223
-dagster_dingtalk-0.1.10b1.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
-dagster_dingtalk-0.1.10b1.dist-info/RECORD,,