SOAP API 開発者ガイド
jlogin()
ログインサーバにログインし、クライアントセッションを開始します。
構文
1LoginResult = connection.login(string username, string password);使用方法
login() コールを使用して、ログインサーバにログインし、クライアントセッションを開始します。クライアントアプリケーションは、他の API コールを行う前に、ログインし、sessionId とサーバ URL を取得しておく必要があります。
クライアントアプリケーションは、login() コールを呼び出すとき、ユーザ認証情報としてユーザ名とパスワードを渡します。呼び出し時に、API が認証を行い、後続のすべての API で使用する、セッションの sessionId、ログインユーザ名に関連付けられているユーザ ID、および Force.com API を指す URL を返します。
Salesforce は、クライアントアプリケーションがログインしている IP アドレスを確認し、不明な IP アドレスからのログインをブロックします。API 経由でブロックされたログインに関しては、Salesforce がログイン失敗エラーを返します。この場合、ユーザはログインパスワードにセキュリティトークンを追加する必要があります。セキュリティトークンは Salesforce から自動生成されるキーです。たとえば、パスワードが mypassword で、セキュリティトークンが XXXXXXXXXX の場合は、ログイン時に「mypasswordXXXXXXXXXX」と入力する必要があります。セキュリティトークンを取得するには、Salesforce ユーザインターフェースを通じてパスワードを変更するか、セキュリティトークンをリセットします。ユーザがパスワードを変更するか、セキュリティトークンをリセットすると、ユーザの Salesforce レコードに指定されたメールアドレス宛に新しいセキュリティトークンが送信されます。セキュリティトークンは、ユーザがセキュリティトークンをリセットするか、パスワードを変更するか、またはパスワードをリセットするまで有効です。セキュリティトークンが無効である場合、ユーザはログインプロセスを繰り返さなければなりません。このような事態を発生させないために、管理者は組織の所有する信頼できる IP アドレスの一覧にクライアントの IP アドレスが追加されていることを確認しなければなりません。詳細は、「セキュリティトークン」を参照してください。
ログイン後、クライアントアプリケーションは、次のタスクを実行する必要があります。
- API がこのセッションに対する後続要求を検証できるように、SOAP ヘッダー内にセッション ID を設定する。
- 後続サービス要求の要求先としてサーバ URL を指定する。ログインサーバはログインコールしかサポートしないため、サーバ URL を変更する必要があります。
開発ツールごとに、セッションヘッダーとサーバ URL の指定方法は異なります。詳細は、使用している開発ツールのマニュアルを参照してください。
login() は、1 時間につき 1 ユーザあたり最大 3600 コールに制限されています。この制限を超えると、「Login Rate Exceeded (ログイン数の制限を超えました。)」エラーが表示されます。
Enterprise と Partner エンドポイント
バージョン 11.1 以前の API では、Partner WSDL で構築されたクライアントアプリケーションは Enterprise エンドポイントに要求を送信可能で、Enterprise WSDL で構築されたアプリケーションは Partner エンドポイントに要求を送信可能です。バージョン 12.0 以降では、この機能はサポートされていません。
プロキシを使用したログイン
プロキシ経由で Salesforce にログインする場合は、ログインに使用する ConnectorConfig クラスのインスタンスでプロキシホストおよびポートを設定します。プロキシを認証する必要がある場合は、必要に応じて、ユーザ名およびパスワードを設定する必要がある場合があります。
1ConnectorConfig config = new ConnectorConfig();
2config.setUsername(userId);
3config.setPassword(passwd);
4config.setAuthEndpoint(authEndPoint);
5config.setProxy(proxyHost, proxyPort);
6// Set the username and password if your proxy must be authenticated
7config.setProxyUsername(proxyUsername);
8config.setProxyPassword(proxyPassword);
9try {
10 EnterpriseConnection connection = new EnterpriseConnection(config);
11 // etc.
12} catch (ConnectionException ce) {
13 ce.printStackTrace();
14}セッション終了
クライアントアプリケーションは、セッションを終えるために明示的にログアウトする必要はありません。セッションは、前もって決定された非活動状態の期間の後、自動的に終了します。非活動状態の期間の長さは、[設定] の をクリックすることによって Salesforce で設定できます。デフォルト値は 120 分 (2 時間) です。API コールを行うと、非活動状態タイマーがゼロにリセットされます。
有効なセルフサービスユーザを認証する
アクティブセルフサービスユーザを認証するには、セルフサービスがユーザの認証に対して LoginScopeHeader を使用して、Organization ID を指定します。認証の前提として、セルフサービスユーザが存在しており、かつ有効である必要があります (「SelfServiceUser」参照)。
Salesforce Communities でのカスタマーサービスポータルおよびカスタマーポータルユーザの認証
有効なカスタマーコミュニティユーザまたはカスタマーポータルユーザを認証するには、LoginScopeHeader を使用して、コミュニティを含む組織の Organization ID を指定します。カスタマーコミュニティユーザとカスタマーポータルユーザは、認証される前に存在し、有効で、組織のコミュニティに属している必要があります。
ログアウト
Salesforce では、不要になったセッションを終了するために、必ず logout() をコールすることをお勧めします。これは、ログアウトされるセッションだけでなく、子セッションも終了させます。設定されたセッション終了時間まで待つ代わりにログアウトすることによって、ほとんどの保護が行われます。
サンプルコード —Java
このサンプルでは、指定されたユーザ名、パスワード、および認証エンドポイント URL を使用してユーザをログインします。このサンプルでは、ログインの成功後、ユーザ情報とセッション情報をコンソールに書き込みます。このサンプルを実行する前に、ユーザ名、パスワード、認証エンドポイントの値を有効な値に置き換えてください。
API コールを作成するために必要な Web サービス WSDL を生成してインポートする方法については、「クイックスタート」の「ステップ 2: Web サービス WSDL を生成または取得する」を参照してください。
1swfobject.registerObject("clippy.sforce_api_calls_login_java_sample", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17public boolean loginSample() {
18 boolean success = false;
19 String username = "username";
20 String password = "password";
21 String authEndPoint = "https://login.salesforce.com/services/Soap/c/24.0/";
22
23 try {
24 ConnectorConfig config = new ConnectorConfig();
25 config.setUsername(username);
26 config.setPassword(password);
27
28 System.out.println("AuthEndPoint: " + authEndPoint);
29 config.setAuthEndpoint(authEndPoint);
30
31 connection = new EnterpriseConnection(config);
32
33 // Print user and session info
34 GetUserInfoResult userInfo = connection.getUserInfo();
35 System.out.println("UserID: " + userInfo.getUserId());
36 System.out.println("User Full Name: " + userInfo.getUserFullName());
37 System.out.println("User Email: " + userInfo.getUserEmail());
38 System.out.println();
39 System.out.println("SessionID: " + config.getSessionId());
40 System.out.println("Auth End Point: " + config.getAuthEndpoint());
41 System.out
42 .println("Service End Point: " + config.getServiceEndpoint());
43 System.out.println();
44
45 success = true;
46 } catch (ConnectionException ce) {
47 ce.printStackTrace();
48 }
49
50 return success;
51}サンプルコード —C#
このサンプルでは、指定されたユーザ名、パスワードを使用してユーザをログインします。login コールの結果には、サービスエンドポイント URL が含まれます。この URL は、組織にサービスしている仮想サーバインスタンスであり、一意のセッション ID です。このサンプルでは、バインドにこれらの返された値を設定します。バインド URL に返されたサービスエンドポイントを設定します。また、すべての API コールで使用されているセッションヘッダーのセッション ID を設定します。次に、ログインの成功後、ユーザ情報とセッション情報をコンソールに書き込みます。このサンプルを実行する前に、ユーザ名とパスワードの値を有効な値に置き換えてください。
API コールを作成するために必要な Web サービス WSDL を生成してインポートする方法については、『クイックスタート』の「ステップ 2: Web サービス WSDL を生成または取得する」を参照してください。
1swfobject.registerObject("clippy.CodeblockPrivateVoidLoginC...-027378D1", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17public bool loginSample()
18{
19 Boolean success = false;
20 string username = "username";
21 string password = "password";
22
23 // Create a service object
24 binding = new SforceService();
25
26 LoginResult lr;
27 try
28 {
29 Console.WriteLine("\nLogging in...\n");
30 lr = binding.login(username, password);
31
32 /**
33 * The login results contain the endpoint of the virtual server instance
34 * that is servicing your organization. Set the URL of the binding
35 * to this endpoint.
36 */
37 // Save old authentication end point URL
38 String authEndPoint = binding.Url;
39 // Set returned service endpoint URL
40 binding.Url = lr.serverUrl;
41
42 /** Get the session ID from the login result and set it for the
43 * session header that will be used for all subsequent calls.
44 */
45 binding.SessionHeaderValue = new SessionHeader();
46 binding.SessionHeaderValue.sessionId = lr.sessionId;
47
48 // Print user and session info
49 GetUserInfoResult userInfo = lr.userInfo;
50 Console.WriteLine("UserID: " + userInfo.userId);
51 Console.WriteLine("User Full Name: " +
52 userInfo.userFullName);
53 Console.WriteLine("User Email: " +
54 userInfo.userEmail);
55 Console.WriteLine();
56 Console.WriteLine("SessionID: " +
57 lr.sessionId);
58 Console.WriteLine("Auth End Point: " +
59 authEndPoint);
60 Console.WriteLine("Service End Point: " +
61 lr.serverUrl);
62 Console.WriteLine();
63
64 // Return true to indicate that we are logged in, pointed
65 // at the right URL and have our security token in place.
66 success = true;
67 }
68 catch (SoapException e)
69 {
70 Console.WriteLine("An unexpected error has occurred: " +
71 e.Message + "\n" + e.StackTrace);
72 }
73 return success;
74}