阿里雲SDK調用簡訊服務API，協助開發人員快速實現安全可靠的簡訊發送功能。 - Short Message Service

在應用開發中，常常需要通過簡訊向使用者發送驗證碼、通知或推廣資訊。例如，使用者在註冊時發送手機驗證碼，或在訂單狀態變更時發送通知。本文旨在為您提供一個快速、安全、可靠的SDK整合方式，以API方式調用阿里雲簡訊服務，實現自動化簡訊發送。

方案架構

調用簡訊服務API的整體流程涉及到開發人員應用、阿里雲SDK、身份與許可權管理（RAM）以及簡訊服務本身。

流程的核心邏輯：開發人員將阿里雲 SDK 整合至應用中，並通過 RAM 為應用程式指派具有簡訊服務許可權的訪問憑證。應用使用該憑證調用阿里雲簡訊服務的API發送請求，阿里雲服務端完成鑒權與合規校正後，將訊息交由簡訊網關處理，並通過電訊廠商網路最終將簡訊送達目標使用者手機。

以傳送簡訊（SendMessageToGlobe）介面為例，引導您完成簡訊服務API調用。您將瞭解到：

如何建立RAM使用者並授權。
如何安裝SDK。
如何調用簡訊服務API。

說明

如果您已經熟悉如何調用API，可直接查閱API目錄，調用所需介面。
推薦使用SDK整合的方法對API進行調用。如果您希望自訂封裝請求對API進行調用，請參見V3版本請求體&簽名機制。

準備工作

準備事項	說明	相關文檔
使用者權限	您可以通過RAM控制台，單擊RAM使用者名稱稱查看使用者權限。請確保您需要調用API的RAM使用者已有簡訊服務相關許可權： AliyunDysmsFullAccess：管理簡訊服務的許可權。	建立RAM使用者並完成授權自訂授權資訊
`AccessKey ID`	可以通過RAM控制台，單擊RAM使用者名稱稱進入詳情頁，點擊AccessKey頁簽，查看AccessKey ID。	建立RAM使用者並完成授權
`AccessKey Secret`	建立後不支援二次查看，若本地無備份，建議重新建立一對AccessKey使用。	建立RAM使用者並完成授權
賬戶餘額/套餐包餘量	確保賬戶餘額充足或套餐包餘量充足。您可以在控制台套餐包統計介面查看套餐包餘量，或在費用與成本介面查看賬戶餘額。	產品計費

配置憑證

步驟一：建立RAM使用者並完成授權

重要

阿里雲主帳號擁有較高許可權，建議您通過RAM使用者進行API調用和日常營運。有關RAM使用者的更多資訊，請參見RAM使用者概覽。

建立RAM使用者：訪問建立RAM使用者，完成相關名稱設定，並選擇訪問配置為使用永久 AccessKey 訪問，單擊確認後即可完成RAM使用者的建立。請及時儲存AccessKey資訊。
為RAM使用者授權：訪問RAM使用者列表，找到您所建立的RAM使用者，單擊操作列的新增授權。在權限策略文本搜尋方塊中輸入AliyunDysmsFullAccess後選中此策略，單擊確認新增授權，即可完成授權操作。

說明

AliyunDysmsFullAccess：管理簡訊服務的許可權。
AliyunDysmsReadOnlyAccess：唯讀訪問簡訊服務的許可權。
如果您需要建立自訂許可權，請參見授權資訊。

步驟二：擷取訪問憑證

請配置環境變數，通過環境變數讀取存取金鑰（AccessKey）。環境變數配置方法，請參見在Linux、macOS和Windows系統配置環境變數。

說明

為避免在代碼中寫入程式碼AccessKey而造成泄露，請通過配置環境變數的方式，來擷取AccessKey。
本文程式碼範例以環境變數名ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET為例，進行後續操作。

步驟三：環境變數配置步驟

Windows系統

在Windows系統中，您可以通過系統屬性、CMD或PowerShell配置環境變數。

系統屬性

說明

此方式配置的環境變數永久生效。
修改系統內容變數需具備管理員權限。
配置環境變數後不會立即影響已經開啟的命令視窗、IDE或其他正在啟動並執行應用程式。您需要重新啟動這些程式或者開啟新的命令列使環境變數生效。

在Windows系統案頭中按Win+Q鍵，在搜尋方塊中搜尋編輯系統內容變數，單擊開啟系統屬性介面。
在系統屬性視窗，單擊環境變數，然後在系統變數地區下單擊建立，變數名填入ALIBABA_CLOUD_ACCESS_KEY_ID，變數值填入您的AccessKey ID。設定ALIBABA_CLOUD_ACCESS_KEY_SECRET的操作相同。
依次單擊三個視窗的確定，關閉系統屬性配置頁面，完成環境變數配置。
開啟CMD（命令提示字元）視窗或Windows PowerShell視窗，執行如下命令檢查環境變數是否生效。
1. CMD查詢命令：
```
echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%
```
2. Windows PowerShell查詢命令：
```
echo $env:ALIBABA_CLOUD_ACCESS_KEY_ID
echo $env:ALIBABA_CLOUD_ACCESS_KEY_SECRET
```

CMD

添加永久性環境變數

如果您希望API Key環境變數在目前使用者的所有新會話中生效，可以按如下操作。

在CMD中運行以下命令。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
setx ALIBABA_CLOUD_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
setx ALIBABA_CLOUD_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

開啟一個新的CMD視窗。

在新的CMD視窗運行以下命令，檢查環境變數是否生效。

echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%

添加臨時性環境變數

如果您僅希望在當前會話中使用該環境變數，可以在CMD中運行以下命令。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
set ALIBABA_CLOUD_ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
set ALIBABA_CLOUD_ACCESS_KEY_SECRET=YOUR_ACCESS_KEY_SECRET

您可以在當前會話運行以下命令檢查環境變數是否生效。

echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%

PowerShell

添加永久性環境變數

如果您希望API Key環境變數在目前使用者的所有新會話中生效，可以按如下操作。

在PowerShell中運行以下命令。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
[Environment]::SetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
[Environment]::SetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

開啟一個新的PowerShell視窗。

在新的PowerShell視窗運行以下命令，檢查環境變數是否生效。

echo $env:ALIBABA_CLOUD_ACCESS_KEY_ID
echo $env:ALIBABA_CLOUD_ACCESS_KEY_SECRET

添加臨時性環境變數

如果您僅希望在當前會話中使用該環境變數，可以在PowerShell中運行以下命令。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
$env:ALIBABA_CLOUD_ACCESS_KEY_ID = "YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "YOUR_ACCESS_KEY_SECRET"

您可以在當前會話運行以下命令檢查環境變數是否生效。

echo $env:ALIBABA_CLOUD_ACCESS_KEY_ID
echo $env:ALIBABA_CLOUD_ACCESS_KEY_SECRET

Linux系統

添加永久性環境變數

如果您希望API Key環境變數在目前使用者的所有新會話中生效，可以添加永久性環境變數。

執行以下命令來將環境變數設定追加到~/.bashrc 檔案中。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
echo "export ALIBABA_CLOUD_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
echo "export ALIBABA_CLOUD_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

也可以手動修改~/.bashrc 檔案。

手動修改

執行以下命令，開啟~/.bashrc 檔案。

nano ~/.bashrc

在設定檔中添加以下內容。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
export ALIBABA_CLOUD_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="YOUR_ACCESS_KEY_SECRET"

在nano編輯器中，按Ctrl + X，接著按Y，再按Enter以儲存並關閉檔案。

執行以下命令，使變更生效。
```
source ~/.bashrc
```
重新開啟一個終端視窗，運行以下命令檢查環境變數是否生效。建議您使用SDK前重啟IDE。
```
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET
```

添加臨時性環境變數

如果您僅希望在當前會話中使用該環境變數，可以添加臨時性環境變數。

執行以下命令。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
export ALIBABA_CLOUD_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="YOUR_ACCESS_KEY_SECRET"

執行以下命令，驗證該環境變數是否生效。

echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET

macOS系統

添加永久性環境變數

如果您希望API Key環境變數在目前使用者的所有新會話中生效，可以添加永久性環境變數。

在終端中執行以下命令，查看預設Shell類型。
```
echo $SHELL
```

根據預設Shell類型進行操作。

Zsh

執行以下命令來將環境變數設定追加到 ~/.zshrc 檔案中。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
echo "export ALIBABA_CLOUD_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
echo "export ALIBABA_CLOUD_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

也可以手動修改~/.zshrc 檔案。

手動修改

執行以下命令，開啟Shell設定檔。

nano ~/.zshrc

在設定檔中添加以下內容。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
export ALIBABA_CLOUD_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="YOUR_ACCESS_KEY_SECRET"

在nano編輯器中，按Ctrl + X，接著按Y，再按Enter以儲存並關閉檔案。

執行以下命令，使變更生效。
```
source ~/.zshrc
```
重新開啟一個終端視窗，運行以下命令檢查環境變數是否生效。
```
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET
```

Bash

執行以下命令來將環境變數設定追加到 ~/.bash_profile 檔案中。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
echo "export ALIBABA_CLOUD_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
echo "export ALIBABA_CLOUD_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

也可以手動修改~/.bash_profile 檔案。

手動修改

執行以下命令，開啟Shell設定檔。

nano ~/.bash_profile

在設定檔中添加以下內容。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
export ALIBABA_CLOUD_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="YOUR_ACCESS_KEY_SECRET"

在nano編輯器中，按Ctrl + X，接著按Y，再按Enter以儲存並關閉檔案。

執行以下命令，使變更生效。
```
source ~/.bash_profile
```
重新開啟一個終端視窗，運行以下命令檢查環境變數是否生效。
```
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET
```

添加臨時性環境變數

如果您僅希望在當前會話中使用該環境變數，可以添加臨時性環境變數。

以下命令適用於 Zsh 和 Bash。

執行以下命令。

# 用您的 AccessKey ID 代替 YOUR_ACCESS_KEY_ID
export ALIBABA_CLOUD_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID"
# 用您的 AccessKey Secret 代替 YOUR_ACCESS_KEY_SECRET
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="YOUR_ACCESS_KEY_SECRET"

執行以下命令，驗證該環境變數是否生效。

echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET

修改系統內容變數後，請重啟或重新整理您的編譯運行環境，包括IDE、命令列介面、其他傳統型應用程式及後台服務，以確保最新的系統內容變數成功載入。

安裝SDK

本文以Java語言為例，進行後續操作。如果您需要使用其他程式設計語言，請參見SDK參考。

已安裝Java 8或以上版本。
配置Java環境
您可以通過在終端運行以下命令，來檢查您的Java環境：
```
java -version
# 如果使用maven管理和構建java專案，還需確保maven已正確安裝到您的開發環境中
mvn --version
```
以Windows的CMD為例：
為使用簡訊服務SDK，您的Java需要在Java 8或以上版本。您可以查看列印資訊中的第一行確認Java版本，例如列印資訊：openjdk version "16.0.1" 2021-04-20表明當前Java版本為Java 16。如果您當前計算環境沒有Java、或版本低於Java 8，請前往Java下載進行下載與安裝。
您可以通過配置Maven依賴來安裝SDK。請配置以下資訊並將 the-latest-version 替換為最新版本號碼。
```
<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>dysmsapi20180501</artifactId>
  
  <version>the-latest-version</version>
</dependency>
```
Maven配置步驟
1. 開啟您的Maven專案的pom.xml檔案。
2. 在<dependencies>標籤內添加上述依賴資訊。
3. 儲存pom.xml檔案。
4. 右鍵專案名稱，選擇Maven->Reload project，更新專案依賴，Maven會自動下載並添加簡訊服務SDK到您的專案中。

使用SDK

1. 初始化用戶端

阿里雲SDK支援多種訪問憑據用於初始化用戶端，例如AccessKey和STS Token等，更多方式請參見管理訪問憑據。本文以AccessKey初始化用戶端為例，進行後續操作。

package com.aliyun.sample;

import com.aliyun.teaopenapi.models.Config;
import com.aliyun.dysmsapi20180501.Client;

public class Sample {
    public static Client createClient() throws Exception {
        Config config = new Config()
                // 配置 AccessKey ID，請確保代碼運行環境配置了環境變數 ALIBABA_CLOUD_ACCESS_KEY_ID。
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // 配置 AccessKey Secret，請確保代碼運行環境配置了環境變數 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
                // System.getenv()方法表示擷取系統內容變數，不要直接在getenv()中填入AccessKey資訊。
        
        // 配置 Endpoint。
        config.endpoint = "dysmsapi.ap-southeast-1.aliyuncs.com";

        return new Client(config);
    }
}

2. 構建請求對象

構造API請求並根據您的業務需要傳入參數。

說明

請求對象命名規則：{API名稱}Request ，例如SendMessageToGlobe介面的請求對象為SendMessageToGlobeRequest。

SendMessageToGlobeRequest sendSmsRequest = new SendMessageToGlobeRequest()
            .setTo("<YOUR_VALUE>")
            .setMessage("<YOUR_VALUE>");

3. 發起請求

使用SendMessageToGlobe介面完成API請求。

說明

返回對象命名規則：{API名稱}Response ，例如SendMessageToGlobe介面的返回對象為SendMessageToGlobeResponse。

SendMessageToGlobeResponse sendSmsResponse = client.sendMessageToGlobe(sendSmsRequest);

您還可以配置請求參數，具體方法請參見發起請求。
關於逾時和重試的設定，請參見逾時機制和重試機制。
關於SDK異常種類及異常的處理，請參見異常處理。

程式碼範例

完整程式碼範例如下：

package com.aliyun.sample;

import com.aliyun.teaopenapi.models.Config;
import com.aliyun.dysmsapi20180501.Client;
import com.aliyun.dysmsapi20180501.models.SendMessageToGlobeRequest;
import com.aliyun.dysmsapi20180501.models.SendMessageToGlobeResponse;
import static com.aliyun.teautil.Common.toJSONString;

public class Sample {
    public static Client createClient() throws Exception {
        Config config = new Config()
                // 配置 AccessKey ID，請確保代碼運行環境配置了環境變數 ALIBABA_CLOUD_ACCESS_KEY_ID。
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // 配置 AccessKey Secret，請確保代碼運行環境配置了環境變數 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));

        // 配置 Endpoint。
        config.endpoint = "dysmsapi.ap-southeast-1.aliyuncs.com";

        return new Client(config);
    }

    public static void main(String[] args) throws Exception {
        // 初始化請求用戶端
        Client client = Sample.createClient();

        // 構造請求對象，請填入請求參數值
        SendMessageToGlobeRequest sendSmsRequest = new SendMessageToGlobeRequest()
                .setTo("<YOUR_VALUE>")
                .setMessage("<YOUR_VALUE>");

        // 擷取響應對象
        SendMessageToGlobeResponse sendSmsResponse = client.sendMessageToGlobe(sendSmsRequest);

        // 響應包含服務端響應的 body 和 headers
        System.out.println(toJSONString(sendSmsResponse));
    }
}

運行後您將會看到對應的輸出結果：

{
  "headers": {
    "date": "Tue, 24 Oct 2023 07:47:17 GMT",
    "content-type": "application/json;charset=utf-8",
    "content-length": "263",
    "connection": "keep-alive",
    "keep-alive": "timeout=25",
    "access-control-allow-origin": "*",
    "access-control-expose-headers": "*",
    "x-acs-request-id": "97B1D7B6-F2F6-3A50-97BC-A90B43EC962F",
    "x-acs-trace-id": "29c11fe4c778b74774d5f5602f0e7975",
    "etag": "2a+mcDRTDkXqx9VF7b6U57Q3"
  },
  "statusCode": 200,
  "body": {
    "ResponseCode": "OK",
    "NumberDetail": {
    "Region": "Taiwan",
    "Country": "Taiwan, Province of China",
    "Carrier": "FarEasTone"
  },
    "RequestId": "97B1D7B6-F2F6-3A50-97BC-A90B43EC962F",
    "Segments": "1",
    "ResponseDescription": "OK",
    "To": "88691567****",
    "MessageId": "191921698133637273"
  }
}

API錯誤碼及解決方案

具體內容請參見錯誤碼。

成本與風險說明

成本構成：簡訊主要按照發送條數計費，不同省/地區的單價不同。詳細價格請參考產品計費。
關鍵風險：
- 憑據泄露：AccessKey泄露會對該帳號下所有資源的安全帶來威脅，產生非預期的費用以及惡意勒索等，嚴重情況下甚至可能給阿里雲或其他使用者帶來危害。具體內容請參見AccessKey泄露處理方案。
- 內容合規：發送的內容必須遵守目標省/地區的法律法規，否則可能導致發送失敗或賬戶被封鎖。

Short Message Service：首次調用API

方案架構

準備工作

配置憑證

步驟一：建立RAM使用者並完成授權

步驟二：擷取訪問憑證

步驟三：環境變數配置步驟

Windows系統

系統屬性

CMD

添加永久性環境變數

添加臨時性環境變數

PowerShell

添加永久性環境變數

添加臨時性環境變數

Linux系統

添加永久性環境變數

添加臨時性環境變數

macOS系統

添加永久性環境變數

Zsh

Bash

添加臨時性環境變數

安裝SDK

配置Java環境

使用SDK

1. 初始化用戶端

2. 構建請求對象

3. 發起請求

程式碼範例

API錯誤碼及解決方案

成本與風險說明

相關內容