Gitlab Restful API

一、简介

GItlab拥有Restful的API接口来操作其中的资源对象。

Gitlab Restful API Docs:https://docs.gitlab.com/ee/api/README.html#status-codes

1、接口请求方式

  • Endpoint:http://gitlab地址/api/api版本/资源对象/操作URI?参数1&参数2

  • 目前接口版本为V4,V3在11.0版本后已经移除

  • 接口需要认证,支持的验证方式:

    • OAuth2 tokens

      curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/projects"
      # 或者
      curl "https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN"
      
    • Personal access tokens

      curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects"
      # 或者
      curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>"
      # 或者
      curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects"
      
    • Project access tokens

      curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects"
      # 或者
      curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>"
      # 或者
      curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects"
      
    • Session cookie

    • GitLab CI/CD job token

  • 接口返回的是JSON数据格式(在Linux下可以使用jq进行处理)

    curl --header "PRIVATE-TOKEN: <your_access_token>" \
    "https://gitlab.example.com/api/v4/projects" | jq -r '.[].id'
    
  • 如果某些资源对象的URL操作中包含特殊字符,需要做URL编码处理

    例如:资源对象路径包含的/可以使用%2F进行处理

    GET /api/v4/projects/1/repository/files/src%2FREADME.md?ref=master
    GET /api/v4/projects/1/branches/my%2Fbranch/commits
    GET /api/v4/projects/1/repository/tags/my%2Ftag
    
  • 请求资源对象参数中的数组和hash

    • 数组

      curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
      -d "import_sources[]=github" \
      -d "import_sources[]=bitbucket" \
      "https://gitlab.example.com/api/v4/some_endpoint"
      
    • Hash

      curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
      --form "namespace=email" \
      --form "path=impapi" \
      --form "file=@/path/to/somefile.txt"
      --form "override_params[visibility]=private" \
      --form "override_params[some_other_param]=some_value" \
      "https://gitlab.example.com/api/v4/projects/import"
      
    • Hash数组

      curl --globoff --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
      "https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[][key]=VAR1&variables[][value]=hello&variables[][key]=VAR2&variables[][value]=world"
      
      curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
      --header "Content-Type: application/json" \
      --data '{ "ref": "master", "variables": [ {"key": "VAR1", "value": "hello"}, {"key": "VAR2", "value": "world"} ] }' \
      "https://gitlab.example.com/api/v4/projects/169/pipeline"
      
  • 请求分页

    对于一些有大量返回数据的资源请求,gitlab为了保持性能,是有默认分页操作的。支持的分页方式

    • 基于Offset的分页(所有接口都支持)

      • 参数

        | Parameter | Description | | :--------- | :------------------------------------------ | | page | 页数,默认为1 | | per_page | 一页显示的对象个数 (默认: 20,最大: 100) |

        curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/namespaces?per_page=50"
        
      • 分页返回的Header

        curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2"
        
        HTTP/2 200 OK
        cache-control: no-cache
        content-length: 1103
        content-type: application/json
        date: Mon, 18 Jan 2016 09:43:18 GMT
        link: <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="prev", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="next", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=1&per_page=3>; rel="first", <https://gitlab.example.com/api/v4/projects/8/issues/8/notes?page=3&per_page=3>; rel="last"
        status: 200 OK
        vary: Origin
        x-next-page: 3
        x-page: 2
        x-per-page: 3
        x-prev-page: 1
        x-request-id: 732ad4ee-9870-4866-a199-a9db0cde3c86
        x-runtime: 0.108688
        x-total: 8
        x-total-pages: 3
        

        | Header | Description | | :-------------- | :------------- | | x-next-page | 下一页的索引 | | x-page | 当前页的索引 | | x-per-page | 每页的对象个数 | | X-prev-page | 上一页的索引 | | x-total | 所有的对象格式 | | x-total-pages | 所有页的个数 |

    • 基于Keyset的分页(仅支持部分接口 )

      • 参数

        | Parameter | Description | | :----------- | :------------------------------------------ | | pagination | keyset (开启分页使用keyset). | | per_page | 一页显示的对象个数 (默认: 20,最大: 100) |

      • 分页返回的Header

        curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc"
        
        HTTP/1.1 200 OK
            ...
            Links: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next"
            Link: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next"
            Status: 200 OK
            ...
        
  • 接口返回状态码

    | 状态返回码 | 描述 | | :----------------------- | :----------------------------------------------------------- | | 200 OK | GET,PUT或者DELETE请求已处理完成,已返回JSON结构的数据 | | 204 No Content | 接口已处理完成了请求,但是没有什么数据可返回的 | | 201 Created | POST 请求已处理完成,已返回JSON结构的数据 | | 304 Not Modified | 自上次请求以来,该资源尚未修改。 | | 400 Bad Request | 请求参数不完整 | | 401 Unauthorized | 用户未认证,请求需要认证Token | | 403 Forbidden | 请求中认证Token没有相应的权限对请求中的对象进行操作 | | 404 Not Found | 请求操作的资源没发现。可能是参数不对,没有匹配到准确的对象 | | 405 Method Not Allowed | 请求中的资源对象不支持该请求方法 | | 409 Conflict | 请求的资源操作跟已有的现有对象有冲突。 | | 412 | 请求的资源操作被拒绝啦。如果尝试删除资源时提供了If-Unmodified-Since标头,则可能会发生这种情况。 | | 422 Unprocessable | The entity couldn’t be processed. | | 429 Too Many Requests | 请求被限制了! | | 500 Server Error | 在服务端处理请求过程中出现了错误 |

二、Project API

DQL

1、列出所有仓库

Endpoint

GET /projects

文档

https://docs.gitlab.com/ee/api/projects.html#list-all-projects

参数

参数 类型 是否必须 描述
archived boolean No 是否列出archived状态的
id_after integer No Limit results to projects with IDs greater than the specified ID.
id_before integer No Limit results to projects with IDs less than the specified ID.
last_activity_after datetime No Limit results to projects with last_activity after specified time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ
last_activity_before datetime No Limit results to projects with last_activity before specified time. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ
membership boolean No Limit by projects that the current user is a member of.
min_access_level integer No Limit by current user minimal access level.
order_by string No Return projects ordered by id, name, path, created_at, updated_at, or last_activity_at fields. repository_size, storage_size, packages_size or wiki_size fields are only allowed for admins. Default is created_at.
owned boolean No Limit by projects explicitly owned by the current user.
repository_checksum_failed boolean No Limit projects where the repository checksum calculation has failed (Introduced in GitLab Premium 11.2).
repository_storage string No Limit results to projects stored on repository_storage. (admins only)
search_namespaces boolean No Include ancestor namespaces when matching search criteria. Default is false.
search string No Return list of projects matching the search criteria.
simple boolean No Return only limited fields for each project. This is a no-op without authentication as then only simple fields are returned.
sort string No Return projects sorted in asc or desc order. Default is desc.
starred boolean No Limit by projects starred by the current user.
statistics boolean No Include project statistics.
visibility string No Limit by visibility public, internal, or private.
wiki_checksum_failed boolean No Limit projects where the wiki checksum calculation has failed (Introduced in GitLab Premium 11.2).
with_custom_attributes boolean No Include custom attributes in response. (admins only)
with_issues_enabled boolean No Limit by enabled issues feature.
with_merge_requests_enabled boolean No Limit by enabled merge requests feature.
with_programming_language string No Limit by projects which use the given programming language.

示例

GET /projects?custom_attributes[key]=value&custom_attributes[other_key]=other_value
Copyright Curiouser all right reserved,powered by Gitbook该文件最后修改时间: 2021-03-22 21:49:06

results matching ""

    No results matching ""