Gradle 支援 Maven 和 Ivy 儲存庫的各種傳輸協定。

支援的傳輸協定

這些協定決定 Gradle 如何與儲存庫通訊以解析相依性。

類型 憑證類型 連結

檔案

無

http

使用者名稱/密碼

文件

https

使用者名稱/密碼

文件

sftp

使用者名稱/密碼

文件

s3

存取金鑰/私密金鑰/會話權杖或環境變數

文件

gcs

預設應用程式憑證，來源為已知檔案、環境變數等。

文件
使用者名稱和密碼絕不應以純文字形式儲存在您的建置檔案中。相反地，請將憑證儲存在本機 gradle.properties 檔案中，或使用開放原始碼 Gradle 外掛程式來加密和取用憑證，例如 憑證外掛程式。

傳輸協定會指定為儲存庫 URL 的一部分。

以下是如何使用各種協定宣告儲存庫的範例

範例 1. 宣告基於 HTTP 的 Maven 和 Ivy 儲存庫
build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
    }

    ivy {
        url = uri("http://repo.mycompany.com/repo")
    }
}
build.gradle
repositories {
    maven {
        url = "http://repo.mycompany.com/maven2"
    }

    ivy {
        url = "http://repo.mycompany.com/repo"
    }
}
範例 2. 宣告儲存庫的 SFTP 協定
build.gradle.kts
repositories {
    maven {
        url = uri("sftp://repo.mycompany.com:22/maven2")
        credentials {
            username = "user"
            password = "password"
        }
    }

    ivy {
        url = uri("sftp://repo.mycompany.com:22/repo")
        credentials {
            username = "user"
            password = "password"
        }
    }
}
build.gradle
repositories {
    maven {
        url = "sftp://repo.mycompany.com:22/maven2"
        credentials {
            username = "user"
            password = "password"
        }
    }

    ivy {
        url = "sftp://repo.mycompany.com:22/repo"
        credentials {
            username = "user"
            password = "password"
        }
    }
}
範例 3. 宣告 S3 支援的 Maven 和 Ivy 儲存庫
build.gradle.kts
repositories {
    maven {
        url = uri("s3://myCompanyBucket/maven2")
        credentials(AwsCredentials::class) {
            accessKey = "someKey"
            secretKey = "someSecret"
            // optional
            sessionToken = "someSTSToken"
        }
    }

    ivy {
        url = uri("s3://myCompanyBucket/ivyrepo")
        credentials(AwsCredentials::class) {
            accessKey = "someKey"
            secretKey = "someSecret"
            // optional
            sessionToken = "someSTSToken"
        }
    }
}
build.gradle
repositories {
    maven {
        url = "s3://myCompanyBucket/maven2"
        credentials(AwsCredentials) {
            accessKey = "someKey"
            secretKey = "someSecret"
            // optional
            sessionToken = "someSTSToken"
        }
    }

    ivy {
        url = "s3://myCompanyBucket/ivyrepo"
        credentials(AwsCredentials) {
            accessKey = "someKey"
            secretKey = "someSecret"
            // optional
            sessionToken = "someSTSToken"
        }
    }
}
範例 4. 使用 IAM 宣告 S3 支援的 Maven 和 Ivy 儲存庫
build.gradle.kts
repositories {
    maven {
        url = uri("s3://myCompanyBucket/maven2")
        authentication {
            create<AwsImAuthentication>("awsIm") // load from EC2 role or env var
        }
    }

    ivy {
        url = uri("s3://myCompanyBucket/ivyrepo")
        authentication {
            create<AwsImAuthentication>("awsIm")
        }
    }
}
build.gradle
repositories {
    maven {
        url = "s3://myCompanyBucket/maven2"
        authentication {
           awsIm(AwsImAuthentication) // load from EC2 role or env var
        }
    }

    ivy {
        url = "s3://myCompanyBucket/ivyrepo"
        authentication {
           awsIm(AwsImAuthentication)
        }
    }
}
範例 5. 宣告 GCS 支援的 Maven 和 Ivy 儲存庫
build.gradle.kts
repositories {
    maven {
        url = uri("gcs://myCompanyBucket/maven2")
    }

    ivy {
        url = uri("gcs://myCompanyBucket/ivyrepo")
    }
}
build.gradle
repositories {
    maven {
        url = "gcs://myCompanyBucket/maven2"
    }

    ivy {
        url = "gcs://myCompanyBucket/ivyrepo"
    }
}

配置驗證方案

HTTP(S) 驗證方案配置

當配置使用 HTTP 或 HTTPS 傳輸協定的儲存庫時，有幾種驗證方案可用。預設情況下，Gradle 會嘗試使用 Apache HttpClient 程式庫 支援的所有方案。但是，您可能想要明確指定與遠端伺服器互動時應使用哪些驗證方案。明確宣告後，只會使用指定的方案。

基本驗證

您可以使用 PasswordCredentials 為基本驗證保護的 Maven 儲存庫指定憑證

build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
        credentials {
            username = "user"
            password = "password"
        }
    }
}
build.gradle
repositories {
    maven {
        url = "http://repo.mycompany.com/maven2"
        credentials {
            username = "user"
            password = "password"
        }
    }
}

摘要驗證

若要配置儲存庫僅使用 DigestAuthentication

build.gradle.kts
repositories {
    maven {
        url = uri("https://repo.mycompany.com/maven2")
        credentials {
            username = "user"
            password = "password"
        }
        authentication {
            create<DigestAuthentication>("digest")
        }
    }
}
build.gradle
repositories {
    maven {
        url = 'https://repo.mycompany.com/maven2'
        credentials {
            username = "user"
            password = "password"
        }
        authentication {
            digest(DigestAuthentication)
        }
    }
}

支援的驗證方案

BasicAuthentication

透過 HTTP 的基本存取驗證。憑證會預先傳送。

DigestAuthentication

透過 HTTP 的摘要存取驗證。

HttpHeaderAuthentication

基於自訂 HTTP 標頭的驗證，例如私有權杖或 OAuth 權杖。

使用先佔式驗證

預設情況下，Gradle 僅在伺服器以驗證質詢 (HTTP 401) 回應時才提交憑證。但是，某些伺服器可能會以不同的程式碼 (例如，GitHub 傳回 404) 回應，這可能會導致相依性解析失敗。在這種情況下，您可以將 Gradle 配置為透過明確使用 BasicAuthentication 方案來預先傳送憑證

build.gradle.kts
repositories {
    maven {
        url = uri("https://repo.mycompany.com/maven2")
        credentials {
            username = "user"
            password = "password"
        }
        authentication {
            create<BasicAuthentication>("basic")
        }
    }
}
build.gradle
repositories {
    maven {
        url = 'https://repo.mycompany.com/maven2'
        credentials {
            username = "user"
            password = "password"
        }
        authentication {
            basic(BasicAuthentication)
        }
    }
}

使用 HTTP 標頭驗證

對於需要基於權杖、OAuth2 或其他基於 HTTP 標頭的驗證的 Maven 儲存庫，您可以使用 HttpHeaderCredentials 和 HttpHeaderAuthentication

build.gradle.kts
repositories {
    maven {
        url = uri("http://repo.mycompany.com/maven2")
        credentials(HttpHeaderCredentials::class) {
            name = "Private-Token"
            value = "TOKEN"
        }
        authentication {
            create<HttpHeaderAuthentication>("header")
        }
    }
}
build.gradle
repositories {
    maven {
        url = "http://repo.mycompany.com/maven2"
        credentials(HttpHeaderCredentials) {
            name = "Private-Token"
            value = "TOKEN"
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}

AWS S3 儲存庫配置

當配置使用 AWS S3 的儲存庫時，有幾個選項和設定可用。

S3 配置屬性

以下系統屬性可用於配置與 S3 儲存庫的互動

org.gradle.s3.endpoint

當使用非 AWS、與 S3 API 相容的儲存服務時，覆寫 AWS S3 端點。

org.gradle.s3.maxErrorRetry

指定當 S3 伺服器以 HTTP 5xx 狀態碼回應時的最大重試次數。預設值為 3 (如果未指定)。

S3 URL 格式

S3 URL 必須使用「虛擬託管樣式」格式

s3://<bucketName>[.<regionSpecificEndpoint>]/<s3Key>

範例: s3://myBucket.s3.eu-central-1.amazonaws.com/maven/release

  • myBucket: AWS S3 儲存貯體名稱。

  • s3.eu-central-1.amazonaws.com: 選擇性的區域特定端點。

  • /maven/release: AWS S3 金鑰 (儲存貯體中物件的唯一識別碼)。

S3 Proxy 設定

可以使用下列系統屬性配置 S3 的 Proxy

  • 適用於 HTTPS

    • https.proxyHost

    • https.proxyPort

    • https.proxyUser

    • https.proxyPassword

    • http.nonProxyHosts (注意：這不是錯字。) *適用於 HTTP (如果 org.gradle.s3.endpoint 設定為 HTTP URI)

    • http.proxyHost

    • http.proxyPort

    • http.proxyUser

    • http.proxyPassword

    • http.nonProxyHosts

S3 V4 簽章 (AWS4-HMAC-SHA256)

某些 S3 區域 (例如法蘭克福的 eu-central-1) 要求所有 HTTP 請求都必須使用 AWS 的簽章版本 4 簽署。建議在使用需要 V4 簽章的儲存貯體時，指定包含區域特定端點的 S3 URL

s3://somebucket.s3.eu-central-1.amazonaws.com/maven/release

如果未針對需要 V4 簽章的儲存貯體指定區域特定端點，Gradle 會預設為 us-east-1 區域，並發出警告

Attempting to re-send the request to .... with AWS V4 authentication. To avoid this warning in the future, use region-specific endpoint to access buckets located in regions that require V4 signing.

未能為此類儲存貯體指定區域特定端點會導致

  • 增加網路流量：每個檔案上傳/下載到 AWS 的來回行程為三次，而不是一次。

  • 建置速度較慢：由於網路延遲增加。

  • 更高的傳輸失敗率：由於額外的網路負擔。

S3 跨帳戶存取

在具有多個 AWS 帳戶 (例如，每個團隊一個) 的組織中，儲存貯體擁有者可能與成品發佈者或取用者不同。為了確保取用者可以存取成品，儲存貯體擁有者必須授予適當的存取權。Gradle 會自動將 bucket-owner-full-control Canned ACL 應用於上傳的物件。請確保發佈者具有必要的 IAM 許可 (PutObjectAcl 和 PutObjectVersionAcl，如果已啟用儲存貯體版本控制)，可以直接或透過假設的 IAM 角色取得。如需更多詳細資訊，請參閱 AWS S3 存取權限。

Google Cloud Storage 儲存庫配置

當配置使用 Google Cloud Storage (GCS) 的儲存庫時，有幾個配置選項和設定可用。

GCS 配置屬性

您可以使用下列系統屬性來配置與 GCS 儲存庫的互動

org.gradle.gcs.endpoint

覆寫 Google Cloud Storage 端點，當使用與 GCS API 相容但不託管在 Google Cloud Platform 上的儲存服務時非常有用。

org.gradle.gcs.servicePath

指定 GCS 用戶端從中建置請求的根服務路徑，預設值為 /。

GCS URL 格式

GCS URL 使用「虛擬託管樣式」格式，且必須遵守下列結構

gcs://<bucketName>/<objectKey>

  • <bucketName>: Google Cloud Storage 儲存貯體的名稱。

  • <objectKey>: 儲存貯體中物件的唯一識別碼。

範例: gcs://myBucket/maven/release

  • myBucket: 儲存貯體名稱。

  • /maven/release: GCS 物件金鑰。

處理憑證

儲存庫憑證絕不應硬式編碼在您的建置腳本中，而應保持外部化。Gradle 在 成品儲存庫中提供 API，讓您可以宣告所需的憑證類型，其值會在建置期間從 Gradle 屬性 查閱。

例如，考慮下列儲存庫配置

build.gradle.kts
repositories {
    maven {
        name = "mySecureRepository"
        credentials(PasswordCredentials::class)
        // url = uri(<<some repository url>>)
    }
}
build.gradle
repositories {
    maven {
        name = 'mySecureRepository'
        credentials(PasswordCredentials)
        // url = uri(<<some repository url>>)
    }
}

在此範例中，使用者名稱和密碼會自動從名為 mySecureRepositoryUsername 和 mySecureRepositoryPassword 的屬性查閱。

配置屬性前綴

配置屬性前綴 (稱為身分) 是從儲存庫名稱衍生而來。憑證可以透過任何支援的 Gradle 屬性機制提供：gradle.properties 檔案、命令列引數、環境變數或這些機制的組合。

條件式憑證需求

只有在建置流程需要憑證時才需要憑證。例如，如果專案配置為將成品發佈到受保護的儲存庫，但未調用發佈工作，則 Gradle 不會要求憑證。但是，如果需要憑證的工作是建置流程的一部分，則 Gradle 會在執行任何工作之前檢查憑證是否存在，以防止因缺少憑證而導致建置失敗。

支援的憑證類型

查閱僅支援下表列出的憑證類型

類型 引數 基礎屬性名稱 是否必要？

PasswordCredentials

username

使用者名稱

必要

password

密碼

必要

AwsCredentials

accessKey

存取金鑰

必要

secretKey

私密金鑰

必要

sessionToken

會話權杖

選用

HttpHeaderCredentials

name

AuthHeaderName

必要

value

AuthHeaderValue

必要