残業ルール設定の一括照会

この API を呼び出すと、複数の残業ルール ID を指定して、残業ルール設定の詳細を一括で照会できます。

API 呼び出し説明

たとえば、社内の勤怠グループで、残業ルールが 承認時間に基づいて残業を計算 に設定されているとします。 DingTalk の管理コンソールで、勤怠グループ管理 > 勤怠グループを変更 > 残業ルール > 設定の順に移動します。一般の残業ルールは 承認時間に基づいて残業を計算 に設定されています。この設定は勤務日・休日・祝日のすべてに適用されます。残業には承認が必要で、残業時間は承認フォームに基づいて計算されます。この API を呼び出すと、承認時間に基づいて残業を計算 という残業ルールの設定詳細を取得できます。取得できる情報には、ルール名や残業時間の計算方法が含まれます。管理コンソールで 勤怠ルール管理 > 残業ルール を開き、残業ルールを編集します。残業ルールを編集 パネルには、次の設定項目があります。

フィールド	選択肢 / 備考
ルール名	最大 30 文字
適用範囲	例：社内全体（他の残業ルールが適用されているメンバーを除く）
所有者	任意
日の種類タブ	勤務日、休日、祝日
残業を許可	オン / オフの切り替え
残業可能な時間帯	始業前、終業後
計算方法	承認時間に基づいて計算、または承認期間内の打刻時間に基づいて計算

この例のルールでは、承認時間に基づいて計算 の方法を使用しています。

リクエスト

基本情報

フィールド	値
HTTP URL	https://api.dingtalk.io/v1.0/attendance/overtimeSettings/query
HTTP メソッド	POST
対応するアプリの種類	appType-社内アプリ　appType-サードパーティ社内アプリ
権限	permission-qyapi_attendance_group_read-勤怠グループの照会権限

リクエストヘッダー

名前	タイプ	必須	説明
x-acs-dingtalk-access-token	文字列	はい	この API を呼び出すためのアクセス認証情報です。次の方法で取得します。 - 社内アプリ：社内アプリのアクセストークンを取得 API を呼び出します。 - サードパーティ社内アプリ：サードパーティアプリに権限を付与した組織のアクセストークンを取得する API を呼び出します。

リクエストボディ

名前	タイプ	必須	説明
overtimeSettingIds	long の配列	いいえ	残業ルール設定の ID です。ユーザーのシフト設定情報を照会 API を呼び出し、features 内の overtimeSettingId フィールドから取得します。

リクエスト例

HTTP

POST /v1.0/attendance/overtimeSettings/query HTTP/1.1
Host:api.dingtalk.io
x-acs-dingtalk-access-token:1d96xxxx
Content-Type:application/json

{
  "overtimeSettingIds" : [ 12345678 ]
}

Java

// このファイルは自動生成されています。編集しないでください。
package com.aliyun.sample;

import com.aliyun.tea.*;
import com.aliyun.teautil.*;
import com.aliyun.teautil.models.*;
import com.aliyun.dingtalkattendance_1_0.*;
import com.aliyun.dingtalkattendance_1_0.models.*;
import com.aliyun.teaopenapi.*;
import com.aliyun.teaopenapi.models.*;

public class Sample {

    /**
     * トークンを使用してアカウントの Client を初期化します
     * @return Client
     * @throws Exception
     */
    public static com.aliyun.dingtalkattendance_1_0.Client createClient() throws Exception {
        Config config = new Config();
        config.protocol = "https";
        config.regionId = "central";
        return new com.aliyun.dingtalkattendance_1_0.Client(config);
    }

    public static void main(String[] args_) throws Exception {
        java.util.List<String> args = java.util.Arrays.asList(args_);
        com.aliyun.dingtalkattendance_1_0.Client client = Sample.createClient();
        GetOvertimeSettingHeaders getOvertimeSettingHeaders = new GetOvertimeSettingHeaders();
        getOvertimeSettingHeaders.xAcsDingtalkAccessToken = "<your access token>";
        GetOvertimeSettingRequest getOvertimeSettingRequest = new GetOvertimeSettingRequest()
                .setOvertimeSettingIds(java.util.Arrays.asList(
                    12345678L
                ));
        try {
            client.getOvertimeSettingWithOptions(getOvertimeSettingRequest, getOvertimeSettingHeaders, new RuntimeOptions());
        } catch (TeaException err) {
            if (!com.aliyun.teautil.Common.empty(err.code) && !com.aliyun.teautil.Common.empty(err.message)) {
                // err には問題の調査に役立つ code 属性と message 属性が含まれます
            }

        } catch (Exception _err) {
            TeaException err = new TeaException(_err.getMessage(), _err);
            if (!com.aliyun.teautil.Common.empty(err.code) && !com.aliyun.teautil.Common.empty(err.message)) {
                // err には問題の調査に役立つ code 属性と message 属性が含まれます
            }

        }        
    }
}

Python

# -*- coding: utf-8 -*-
# このファイルは自動生成されています。編集しないでください。
import sys

from typing import List

from alibabacloud_dingtalk.attendance_1_0.client import Client as dingtalkattendance_1_0Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_dingtalk.attendance_1_0 import models as dingtalkattendance__1__0_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient

class Sample:
    def __init__(self):
        pass

    @staticmethod
    def create_client() -> dingtalkattendance_1_0Client:
        """
        トークンを使用してアカウントの Client を初期化します
        @return: Client
        @throws Exception
        """
        config = open_api_models.Config()
        config.protocol = 'https'
        config.region_id = 'central'
        return dingtalkattendance_1_0Client(config)

    @staticmethod
    def main(
        args: List[str],
    ) -> None:
        client = Sample.create_client()
        get_overtime_setting_headers = dingtalkattendance__1__0_models.GetOvertimeSettingHeaders()
        get_overtime_setting_headers.x_acs_dingtalk_access_token = '<your access token>'
        get_overtime_setting_request = dingtalkattendance__1__0_models.GetOvertimeSettingRequest(
            overtime_setting_ids=[
                12345678
            ]
        )
        try:
            client.get_overtime_setting_with_options(get_overtime_setting_request, get_overtime_setting_headers, util_models.RuntimeOptions())
        except Exception as err:
            if not UtilClient.empty(err.code) and not UtilClient.empty(err.message):
                # err には問題の調査に役立つ code 属性と message 属性が含まれます
                pass

    @staticmethod
    async def main_async(
        args: List[str],
    ) -> None:
        client = Sample.create_client()
        get_overtime_setting_headers = dingtalkattendance__1__0_models.GetOvertimeSettingHeaders()
        get_overtime_setting_headers.x_acs_dingtalk_access_token = '<your access token>'
        get_overtime_setting_request = dingtalkattendance__1__0_models.GetOvertimeSettingRequest(
            overtime_setting_ids=[
                12345678
            ]
        )
        try:
            await client.get_overtime_setting_with_options_async(get_overtime_setting_request, get_overtime_setting_headers, util_models.RuntimeOptions())
        except Exception as err:
            if not UtilClient.empty(err.code) and not UtilClient.empty(err.message):
                # err には問題の調査に役立つ code 属性と message 属性が含まれます
                pass

if __name__ == '__main__':
    Sample.main(sys.argv[1:])

PHP

<?php

// このファイルは自動生成されています。編集しないでください。
namespace AlibabaCloud\SDK\Sample;

use AlibabaCloud\SDK\Dingtalk\Vattendance_1_0\Dingtalk;
use \Exception;
use AlibabaCloud\Tea\Exception\TeaError;
use AlibabaCloud\Tea\Utils\Utils;

use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\SDK\Dingtalk\Vattendance_1_0\Models\GetOvertimeSettingHeaders;
use AlibabaCloud\SDK\Dingtalk\Vattendance_1_0\Models\GetOvertimeSettingRequest;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;

class Sample {

    /**
     * トークンを使用してアカウントの Client を初期化します
     * @return Dingtalk Client
     */
    public static function createClient(){
        $config = new Config([]);
        $config->protocol = "https";
        $config->regionId = "central";
        return new Dingtalk($config);
    }

    /**
     * @param string[] $args
     * @return void
     */
    public static function main($args){
        $client = self::createClient();
        $getOvertimeSettingHeaders = new GetOvertimeSettingHeaders([]);
        $getOvertimeSettingHeaders->xAcsDingtalkAccessToken = "<your access token>";
        $getOvertimeSettingRequest = new GetOvertimeSettingRequest([
            "overtimeSettingIds" => [
                12345678
            ]
        ]);
        try {
            $client->getOvertimeSettingWithOptions($getOvertimeSettingRequest, $getOvertimeSettingHeaders, new RuntimeOptions([]));
        }
        catch (Exception $err) {
            if (!($err instanceof TeaError)) {
                $err = new TeaError([], $err->getMessage(), $err->getCode(), $err);
            }
            if (!Utils::empty_($err->code) && !Utils::empty_($err->message)) {
                // err には問題の調査に役立つ code 属性と message 属性が含まれます
            }
        }
    }
}
$path = __DIR__ . \DIRECTORY_SEPARATOR . '..' . \DIRECTORY_SEPARATOR . 'vendor' . \DIRECTORY_SEPARATOR . 'autoload.php';
if (file_exists($path)) {
    require_once $path;
}
Sample::main(array_slice($argv, 1));

// このファイルは自動生成されています。編集しないでください。
package main

import (
  "os"
  util  "github.com/alibabacloud-go/tea-utils/service"
  dingtalkattendance_1_0  "github.com/alibabacloud-go/dingtalk/attendance_1_0"
  openapi  "github.com/alibabacloud-go/darabonba-openapi/client"
  "github.com/alibabacloud-go/tea/tea"
)

/**
 * トークンを使用してアカウントの Client を初期化します
 * @return Client
 * @throws Exception
 */
func CreateClient () (_result *dingtalkattendance_1_0.Client, _err error) {
  config := &openapi.Config{}
  config.Protocol = tea.String("https")
  config.RegionId = tea.String("central")
  _result = &dingtalkattendance_1_0.Client{}
  _result, _err = dingtalkattendance_1_0.NewClient(config)
  return _result, _err
}

func _main (args []*string) (_err error) {
  client, _err := CreateClient()
  if _err != nil {
    return _err
  }

  getOvertimeSettingHeaders := &dingtalkattendance_1_0.GetOvertimeSettingHeaders{}
  getOvertimeSettingHeaders.XAcsDingtalkAccessToken = tea.String("<your access token>")
  getOvertimeSettingRequest := &dingtalkattendance_1_0.GetOvertimeSettingRequest{
    OvertimeSettingIds: []*int64{tea.Int(12345678)},
  }
  tryErr := func()(_e error) {
    defer func() {
      if r := tea.Recover(recover()); r != nil {
        _e = r
      }
    }()
    _, _err = client.GetOvertimeSettingWithOptions(getOvertimeSettingRequest, getOvertimeSettingHeaders, &util.RuntimeOptions{})
    if _err != nil {
      return _err
    }

    return nil
  }()

  if tryErr != nil {
    var err = &tea.SDKError{}
    if _t, ok := tryErr.(*tea.SDKError); ok {
      err = _t
    } else {
      err.Message = tea.String(tryErr.Error())
    }
    if !tea.BoolValue(util.Empty(err.Code)) && !tea.BoolValue(util.Empty(err.Message)) {
      // err には問題の調査に役立つ code 属性と message 属性が含まれます
    }

  }
  return _err
}

func main() {
  err := _main(tea.StringSlice(os.Args[1:]))
  if err != nil {
    panic(err)
  }
}

Node.js

// このファイルは自動生成されています。編集しないでください。
import Util, * as $Util from '@alicloud/tea-util';
import dingtalkattendance_1_0, * as $dingtalkattendance_1_0 from '@alicloud/dingtalk/attendance_1_0';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import * as $tea from '@alicloud/tea-typescript';

export default class Client {

  /**
   * トークンを使用してアカウントの Client を初期化します
   * @return Client
   * @throws Exception
   */
  static createClient(): dingtalkattendance_1_0 {
    let config = new $OpenApi.Config({ });
    config.protocol = "https";
    config.regionId = "central";
    return new dingtalkattendance_1_0(config);
  }

  static async main(args: string[]): Promise<void> {
    let client = Client.createClient();
    let getOvertimeSettingHeaders = new $dingtalkattendance_1_0.GetOvertimeSettingHeaders({ });
    getOvertimeSettingHeaders.xAcsDingtalkAccessToken = "<your access token>";
    let getOvertimeSettingRequest = new $dingtalkattendance_1_0.GetOvertimeSettingRequest({
      overtimeSettingIds: [
        12345678
      ],
    });
    try {
      await client.getOvertimeSettingWithOptions(getOvertimeSettingRequest, getOvertimeSettingHeaders, new $Util.RuntimeOptions({ }));
    } catch (err) {
      if (!Util.empty(err.code) && !Util.empty(err.message)) {
        // err には問題の調査に役立つ code 属性と message 属性が含まれます
      }

    }    
  }

}

Client.main(process.argv.slice(2));

// このファイルは自動生成されています。編集しないでください。

using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;

using Tea;
using Tea.Utils;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample 
    {

        /**
         * トークンを使用してアカウントの Client を初期化します
         * @return Client
         * @throws Exception
         */
        public static AlibabaCloud.SDK.Dingtalkattendance_1_0.Client CreateClient()
        {
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config();
            config.Protocol = "https";
            config.RegionId = "central";
            return new AlibabaCloud.SDK.Dingtalkattendance_1_0.Client(config);
        }

        public static void Main(string[] args)
        {
            AlibabaCloud.SDK.Dingtalkattendance_1_0.Client client = CreateClient();
            AlibabaCloud.SDK.Dingtalkattendance_1_0.Models.GetOvertimeSettingHeaders getOvertimeSettingHeaders = new AlibabaCloud.SDK.Dingtalkattendance_1_0.Models.GetOvertimeSettingHeaders();
            getOvertimeSettingHeaders.XAcsDingtalkAccessToken = "<your access token>";
            AlibabaCloud.SDK.Dingtalkattendance_1_0.Models.GetOvertimeSettingRequest getOvertimeSettingRequest = new AlibabaCloud.SDK.Dingtalkattendance_1_0.Models.GetOvertimeSettingRequest
            {
                OvertimeSettingIds = new List<long?>
                {
                    12345678
                },
            };
            try
            {
                client.GetOvertimeSettingWithOptions(getOvertimeSettingRequest, getOvertimeSettingHeaders, new AlibabaCloud.TeaUtil.Models.RuntimeOptions());
            }
            catch (TeaException err)
            {
                if (!AlibabaCloud.TeaUtil.Common.Empty(err.Code) && !AlibabaCloud.TeaUtil.Common.Empty(err.Message))
                {
                    // err には問題の調査に役立つ code 属性と message 属性が含まれます
                }
            }
            catch (Exception _err)
            {
                TeaException err = new TeaException(new Dictionary<string, object>
                {
                    { "message", _err.Message }
                });
                if (!AlibabaCloud.TeaUtil.Common.Empty(err.Code) && !AlibabaCloud.TeaUtil.Common.Empty(err.Message))
                {
                    // err には問題の調査に役立つ code 属性と message 属性が含まれます
                }
            }
        }

    }
}

C++

// このファイルは自動生成されています。編集しないでください。

#include <alibabacloud/dingtalkattendance__1__0.hpp>
#include <alibabacloud/open_api.hpp>
#include <boost/any.hpp>
#include <darabonba/core.hpp>
#include <darabonba/util.hpp>
#include <iostream>
#include <map>
#include <vector>

using namespace std;

Alibabacloud_Dingtalkattendance_1_0::Client createClient() {
  shared_ptr<Alibabacloud_OpenApi::Config> config = make_shared<Alibabacloud_OpenApi::Config>();
  config->protocol = make_shared<string>("https");
  config->regionId = make_shared<string>("central");
  return Alibabacloud_Dingtalkattendance_1_0::Client(config);
}

int main(int argc, char *args[]) {
  args++;
  shared_ptr<Alibabacloud_Dingtalkattendance_1_0::Client> client = make_shared<Alibabacloud_Dingtalkattendance_1_0::Client>(createClient());
  shared_ptr<Alibabacloud_Dingtalkattendance_1_0::GetOvertimeSettingHeaders> getOvertimeSettingHeaders = make_shared<Alibabacloud_Dingtalkattendance_1_0::GetOvertimeSettingHeaders>();
  getOvertimeSettingHeaders->xAcsDingtalkAccessToken = make_shared<string>("<your access token>");
  shared_ptr<Alibabacloud_Dingtalkattendance_1_0::GetOvertimeSettingRequest> getOvertimeSettingRequest = make_shared<Alibabacloud_Dingtalkattendance_1_0::GetOvertimeSettingRequest>(map<string, boost::any>({
    {"overtimeSettingIds", boost::any(vector<long>({
      12345678
    }))}
  }));
  try {
    client->getOvertimeSettingWithOptions(getOvertimeSettingRequest, getOvertimeSettingHeaders, make_shared<Darabonba_Util::RuntimeOptions>(Darabonba_Util::RuntimeOptions()));
  }
  catch (std::exception &err) {
    if (!Darabonba_Util::Client::empty(err.code) && !Darabonba_Util::Client::empty(err.message)) {
      // err には問題の調査に役立つ code 属性と message 属性が含まれます
    }
  }
}

レスポンス

レスポンスボディ

名前	タイプ	説明
result	配列	残業設定の詳細のリストです。
settingId	long	設定 ID です。
name	文字列	ルール名です。
default	真偽値	デフォルトのルールかどうかを示します。 - true：はい - false：いいえ
durationSettings	`Map<String, Object>`	残業ルールが適用される日付の種類のリストです。
	オブジェクト	残業ルールの種類の詳細です。
calcType	整数	残業に承認フォームが必要かどうかを示します。有効な値： - 1：承認フォームの提出が必要 - 2：承認フォームは不要 - 3：残業は許可されていない
durationType	整数	計算方法です。有効な値： - 1：承認フォームの時間に基づいて計算 - 2：打刻時間に基づいて計算
overtimeRedress	真偽値	残業時間を代休または残業代として計上するかどうかの切り替えです。
settings	Map	値は残業開始時刻または最短残業時間です。
overtimeRedressBy	文字列	残業時間の計上方法です。有効な値： - vacation：代休として計上 - charge：残業代として計上 - manual：社員が選択
vacationRate	浮動小数点	代休時間の換算比率です。
skipTime	文字列	休憩時間の控除方法です。有効な値： - frame：休憩時間帯で控除 - duration：残業時間に応じて控除
skipTimeByFrames	配列	休憩時間帯による控除の設定です。このパラメータは、skipTime が frame の場合にのみ値を持ちます。
startTime	文字列	開始時刻です。形式は `HH:mm` です。
endTime	文字列	終了時刻です。形式は `HH:mm` です。
valid	真偽値	設定が有効かどうかを示します。 - true：有効 - false：無効
skipTimeByDurations	配列	残業時間に応じた控除の設定です。このパラメータは、skipTime が duration の場合にのみ値を持ちます。
duration	long	1 日あたりの残業時間のしきい値です。単位は秒です。
minus	long	控除される時間です。単位は秒です。
holidayPlanOvertimeRedress	真偽値	休日または祝日にシフト設定された残業を代休または残業代として計上するかどうかの切り替えです。
holidayPlanOvertimeRedressBy	文字列	休日または祝日にシフト設定された残業の計上方法です。有効な値： - vacation：代休として計上 - charge：残業代として計上 - manual：社員が選択
holidayPlanVacationRate	浮動小数点	休日または祝日にシフト設定された残業における代休時間の換算比率です。
warningSettings	配列	アラート設定です。
time	文字列	アラートの種類です。有効な値： - everyday：毎日 - everyweek：毎週 - everymonth：毎月
threshold	long	リマインダーのしきい値です。
action	文字列	値はリスクアラートまたは最大残業時間です。
stepType	整数	残業時間の単位です。
stepValue	浮動小数点	残業時間を丸めるかどうかを示します。単位は時間です。有効な値： - 1：丸めない - その他の値：指定した単位値の倍数に切り捨て
workMinutesPerDay	整数	1 日に相当する時間です。単位は分です。
overtimeDivisions	配列	時間の分割ルールです。
previousDayType	文字列	前日の種類です。
nextDayType	文字列	翌日の種類です。
timeSplitPoint	文字列	時間の分割点です。
id	long	過去の残業ルール設定の ID です。

レスポンスボディの例

HTTP/1.1 200 OK
Content-Type:application/json

{
  "result" : [ {
    "settingId" : 841251521,
    "name" : "テスト用残業ルール名",
    "default" : false,
    "durationSettings" : {
      "key" : {
        "calcType" : 1,
        "durationType" : 2,
        "overtimeRedress" : true,
        "overtimeRedressBy" : "charge",
        "vacationRate" : 1,
        "skipTime" : "frame",
        "skipTimeByFrames" : [ {
          "startTime" : "12:00",
          "endTime" : "13:00",
          "valid" : true
        } ],
        "skipTimeByDurations" : [ {
          "duration" : 18000,
          "minus" : 3600
        } ],
        "holidayPlanOvertimeRedress" : true,
        "holidayPlanOvertimeRedressBy" : "vacation",
        "holidayPlanVacationRate" : 1
      }
    },
    "warningSettings" : [ {
      "time" : "everymonth",
      "threshold" : 129600,
      "action" : "alert"
    } ],
    "stepType" : 0,
    "stepValue" : 1,
    "workMinutesPerDay" : 480,
    "overtimeDivisions" : [ {
      "previousDayType" : "workDay",
      "nextDayType" : "restDay",
      "timeSplitPoint" : "00:00"
    } ],
    "id" : 12345678
  } ]
}

エラーコード

この API の呼び出しに失敗した場合は、エラーメッセージをもとにグローバルエラーコードドキュメントで解決方法を確認してください。

HttpCode	エラーコード	エラーメッセージ	説明
400	invalidSize	サイズが無効です	overtimeSettingIds のサイズが無効です
400	invalidParameter	パラメータエラー	overtimeSettingIds パラメータが無効です
500	systemError	システムエラー	システムエラー

API 呼び出しガイド

認証と認可

連絡先

カレンダー

会議

AI Table

勤怠

Docs とファイル

IM

残業ルール設定の一括照会

API 呼び出し説明

リクエスト

基本情報

リクエストヘッダー

リクエストボディ

リクエスト例

レスポンス

レスポンスボディ

レスポンスボディの例

エラーコード

​API 呼び出し説明

​リクエスト

​基本情報

​リクエストヘッダー

​リクエストボディ

​リクエスト例

​レスポンス

​レスポンスボディ

​レスポンスボディの例

​エラーコード

API 呼び出し説明

リクエスト

基本情報

リクエストヘッダー

リクエストボディ

リクエスト例

レスポンス

レスポンスボディ

レスポンスボディの例

エラーコード